epjdZddlZddlZddlZddlZddlZddlZddlZddlZddl m Z ddl m Z ddl mZmZddlmZmZmZddlmZejeZdZd Zd Zd Zd Zd Zd ZeddZ iddddddddddddddddd d!d"d#d$d%d&d'd(d)d*d+d,d-d.d/d0d1d2d3iZ!d4e"d5e e"fd6Z#d7e"d5e$fd8Z%d4e"d5e&fd9Z'd4e"d:e"d5e"fd;Z(d4e"d:e"d5e)e"fd<Z*d4e"d=e"d>e"d5e&fd?Z+d@e"d5e"fdAZ,d4e"d:e"d5dfdBZ-dCZ.d5e"fdDZ/d4e"d:e"fdEZ0d4e"d:e"d5dfdFZ1d4e"d:e"d5dfdGZ2dHe d5e3fdIZ4dJe dKe d5dfdLZ5dddMdNe e dOe e d5dfdPZ6dHe dQe"d5dfdRZ7GdSdTZ8dS)Ua DM Pairing System Code-based approval flow for authorizing new users on messaging platforms. Instead of static allowlists with user IDs, unknown users receive a one-time pairing code that the bot owner approves via the CLI. Security features (based on OWASP + NIST SP 800-63-4 guidance): - 8-char codes from 32-char unambiguous alphabet (no 0/O/1/I) - Cryptographic randomness via secrets.choice() - 1-hour code expiry - Max 3 pending codes per platform - Rate limiting: 1 request per user per 10 minutes - Lockout after 5 failed approval attempts (1 hour) - File permissions: chmod 0600 on all data files - Codes are never logged to stdout Storage: ~/.hermes/pairing/ N)Path)Optional)expand_whatsapp_aliasesnormalize_whatsapp_identifier)get_default_hermes_rootget_hermes_dirget_hermes_home)atomic_replace ABCDEFGHJKLMNPQRSTUVWXYZ23456789iiXplatforms/pairingpairingtelegramTELEGRAM_ALLOWED_USERSdiscordDISCORD_ALLOWED_USERSwhatsappWHATSAPP_ALLOWED_USERSwhatsapp_cloudWHATSAPP_CLOUD_ALLOWED_USERSslackSLACK_ALLOWED_USERSsignalSIGNAL_ALLOWED_USERSemailEMAIL_ALLOWED_USERSsmsSMS_ALLOWED_USERS mattermostMATTERMOST_ALLOWED_USERSmatrixMATRIX_ALLOWED_USERSdingtalkDINGTALK_ALLOWED_USERSfeishuFEISHU_ALLOWED_USERSwecomWECOM_ALLOWED_USERSwecom_callbackWECOM_CALLBACK_ALLOWED_USERSweixinWEIXIN_ALLOWED_USERS bluebubblesBLUEBUBBLES_ALLOWED_USERSqqbotQQ_ALLOWED_USERSyuanbaoYUANBAO_ALLOWED_USERSplatformreturnc |pd}t|}|r|S ddlm}||}|r|jr|jSn#t$rYnwxYwdS)zReturn the per-platform allowlist env var name, or None. Falls back to the platform registry for plugin platforms so a plugin's own ``allowed_users_env`` is honored too. r)platform_registryN)lowerstrip_PLATFORM_ALLOWLIST_ENVgetgateway.platform_registryr9allowed_users_env Exception)r5env_varr9entrys 5/home/thesage/.hermes/hermes-agent/gateway/pairing.py_allowlist_env_for_platformrD[s B%%''--//H%))(33G ??????!%%h//  +U, +* *      4s*A44 BBrawc@d|dDS)Nc^g|]*}||+S)r;).0uids rC z$_split_allowlist..qs- A A ACSYY[[ ACIIKK A A A,)split)rEs rC_split_allowlistrOps A A399S>> A A AArLcV|pddvS)uKTrue for Baileys WhatsApp and Meta Cloud — same phone/JID identity rules.r8>rr)r;r:)r5s rC _platform_uses_whatsapp_identityrQts* N ! ! # # ) ) + +/M MMrLuser_idct|pd}t|rt|p|S|S)zHNormalize platform-specific user IDs before persisting / comparing them.r8)strr;rQr)r5rR raw_user_ids rC_normalize_user_idrVysIgm$$**,,K'11I,[99H[H rLct|pd}|stS|t||h}t |r"|t ||d|S)zCReturn all known equivalent user IDs for auth / allowlist matching.r8)rTr;setrVrQupdaterdiscard)r5rRrUaliasess rC_user_id_aliasesr\sgm$$**,,K uu .xEEFG'11=.{;;<<< OOB NrLleftrightcnt||}t||}t|o|o||zSz;Return True when two user IDs represent the same principal.)r\bool)r5r]r^ left_aliases right_aliasess rC_user_ids_matchrds=#Hd33L$Xu55M  QQL=4P R RRrLrAc ddlm}m} ||pdS#|$rYnwxYwn#t$rYnwxYwt j|pdS)uRead a platform allowlist env var through the profile secret scope. Under multiplexing the process env may hold ANOTHER profile's allowlist (first-writer-wins YAML→env bridges), so reads must honor the installed scope's verdict — including a scoped miss returning empty rather than borrowing the process value. Unscoped callers (single-profile CLI / admin endpoints) keep the legacy ``os.getenv`` read. TODO(profile-secrets): the grant mirror below still WRITES through ``hermes_cli.config.save_env_value`` / ``remove_env_value``, which target the root ``.env`` — those writes need a profile-aware counterpart before pairing grants can be mirrored correctly under multiplexing. r)UnscopedSecretError get_secretr8)agent.secret_scoperfrgr;r@osgetenv)rArfrgs rC_read_allowlist_envrks FFFFFFFF Jw''-24466 6"    D        Ig   $" + + - --s#6*2626 AAcPt|}|sdSt|}|sdSt|}d|vst||vrdS|t| ddlm}||d|dS#t$rYdSwxYw)uAdd ``user_id`` to the platform allowlist env var IF one is configured. Option (i): only materialize the grant into the allowlist when the operator already runs an allowlist for this platform. On an open gateway (no allowlist) we do nothing — the pairing store remains the grant record and the authz union honors it, so we never silently convert an open gateway into a locked one on first pairing. N*r)save_env_valuerM) rDrkrOrTappendhermes_cli.configrnjoinr@)r5rRrAcurrentidsrns rC_sync_allowlist_addrts*(33G !'**G  7 # #C czzS\\S((JJs7|| 444444w .....      s0%B B%$B%c#JK ddlm}|}n#t$rYdSwxYw|dSt|ddpi}|D]}||V t|ddpi}|D]!}|piD]}||V "dS)zDYield adapters from the in-process GatewayRunner, if one is running.r)_gateway_runner_refNadapters_profile_adapters) gateway.runrvr@getattrvalues)rvrunnerrwadapterprofile_adaptersmappings rC_iter_live_gateway_adaptersrs 333333$$&&  ~vz4006BH??$$  MMMv':DAAGR#**,, 2--//  G"  s  ##c@t|dd}|Ft|dd}|r3t|St|dd}t|pdS)Nr5valuenamer8)rzrTr;r:)r}r5rrs rC_adapter_platform_namersw D11H'400  .u::##%%++-- - 7FD ) )D tzr?? " " ( ( * **rLcN||St|tr3t|}fd|D}d|St|tt frfd|DSt|t tfrfd|DS|S)z?Drop alias-equivalent allowlist entries while preserving ``*``.Nc \g|](}|dkst|t&|)SrmrdrT)rIpartr5rRs rCrKz,_purge_allowlist_entries..s@   s{{/(D#g,,"O"O{ {{rLrMc h|]T}t|dks+tt|tR|USrrTr;rdrIrBr5rRs rC z+_purge_allowlist_entries..`   5zz!!S(("8SZZWFF) (((rLc g|]T}t|dks+tt|tR|USrrrs rCrKz,_purge_allowlist_entries..rrL) isinstancerTrOrqrX frozensetlisttuple)entriesr5rRparts remainings `` rC_purge_allowlist_entriesrs'3# ))     "   xx """'C+,,      &    'D%=))      &    NrLcj|pd}|r#t|pdsdStD]}t ||krt |dr< t t|jpd|||_n#t$rYnwxYwtt|dddd}t|tr=d|vr9 t | d|||d<#t$rYwxYwdS)aClear revoked principals from in-process adapter allowlist snapshots. ``WhatsAppAdapter`` (and Cloud) snapshot ``_allow_from`` at construction. Pairing revoke updates ``WHATSAPP_ALLOWED_USERS`` / cloud env, but when the revoked principal was the sole entry the env key is removed entirely. Intake must not keep authorizing from the stale snapshot until restart. r8N _allow_fromrHconfigextra allow_from)r;r:rTrrhasattrrrXrr@rzrdictr=)r5rR platform_namer}rs rC#_sync_live_adapter_allowlist_removersv^**,,2244M GMr 2 2 8 8 : :.00 !' * *m ; ;  7M * *  &>+1r22M7''##    488'4HH eT " " |u'<'< &>IIl++]G''l##    !s$*B00 B=<B=:'D"" D/.D/ct}|sdSt|}|sdSt|}fd|D}t|t|krdS ddlm}m}|r ||d|n ||n#t$rYnwxYwtdS)aRemove ``user_id`` (and WhatsApp alias equivalents) from the allowlist. Matching must mirror PairingStore / authz WhatsApp alias rules: approve mirrors a normalized phone into ``WHATSAPP_ALLOWED_USERS``, while revoke is often invoked with a JID or device-suffix form. Exact-string delete would leave the allowlist entry and keep the sender authorized. Also clears matching entries from any in-process platform adapter ``_allow_from`` snapshot so sole-entry revocation is effective without a gateway restart. Nc \g|](}|dkst|t&|)Srr)rIir5rRs rCrKz*_sync_allowlist_remove..8s@ 88?8QG EE8 88rLr)rnremove_env_valuerM) rDrkrOlenrprnrrqr@r)r5rRrArrrsrrnrs`` rC_sync_allowlist_remover$s *(33G !'**G  7 # #CI 9~~S!! FFFFFFFF  & N7CHHY$7$7 8 8 8 8  W % % %      '':::::s*5B B-,B-pathc|r` tj|d}t |t r|niS#tjtf$ricYSwxYwiS)Nutf-8encoding)existsjsonloads read_textrrJSONDecodeErrorOSError)rdatas rC_load_json_filerJs~ {{}} :dnngn>>??D%dD11944r 9$g.   III  IsAAA21A2 active_dir alternate_dirc |r*||krdS|dd|dD]}|s||jz }t |}|s3t |}t|}||||kr%t|tj |dddS)aMerge split legacy/new pairing data into the active PairingStore dir. Older installs use ``{HERMES_HOME}/pairing`` while newer code/docs may write ``{HERMES_HOME}/platforms/pairing``. If both directories exist, the gateway must not silently ignore approved users sitting in the inactive location; otherwise already-paired Feishu users get asked for a fresh code. NTparentsexist_okz*.jsonFindent ensure_ascii) rresolvemkdirglobis_filerrrrY _secure_writerdumps)rrsrcdestmergedrrbefores rC_merge_pairing_dirrTs    ! !Z%7%7%9%9]=R=R=T=T%T%TTD111!!(++ R R{{}}  CH$ %%  !$''g g V   $ 6!% P P P Q Q Q R RrLhomeactiverrc|p t}|dz }|dz dz }|pt}||kr|n|}t||dS)Nr platforms)r PAIRING_DIRrr)rrold_dirnew_dir alternates rC_migrate_split_pairing_dirsrnst  $?$$DYG[ 9,G  "{F!>>++w/@/@@@gIvy)))))rLrcj|jddtjt |jd\}} t j|dd5}|||t j | dddn #1swxYwYt|| t j |d dS#t$rYdSwxYw#t$r( t j|n#t$rYnwxYwwxYw) uWrite data to file with restrictive permissions (owner read/write only). Uses a temp-file + atomic rename so readers always see either the old complete file or the new one — never a partial write. Trz.tmp)dirsuffixwrrNi)parentrtempfilemkstemprTrifdopenwriteflushfsyncfilenor chmodr BaseExceptionunlink)rrfdtmp_pathfs rCrr{s  KdT222#DK(8(8HHHLB Yr3 1 1 1 !Q GGDMMM GGIII HQXXZZ  ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! x&&&  HT5 ! ! ! ! !    DD    Ih        D  ss D AB<0 D<CDCDC// C=9D<C==D D2 D D2 D-*D2,D--D2c eZdZdZd2deefdZedeefdZdede fdZ dede fd Z de fd Z d e de fd Zd e d e ddfdZdededefdZdededeefdZdedededefdZdededefdZd2dedefdZd3dedededdfdZdededefdZedededefdZdede ded e de f d!Z d3dedededeefd"Zdededee fd#Zed$edefd%Z ded&edee fd'Z!d2dedefd(Z"d2dede#fd)Z$dededefd*Z%dededdfd+Z&dedefd,Z'deddfd-Z(deddfd.Z)deddfd/Z*d0edefd1Z+dS)4 PairingStorea{ Manages pairing codes and approved user lists. Data files per platform: - {platform}-pending.json : pending pairing requests - {platform}-approved.json : approved (paired) users - _rate_limits.json : rate limit tracking When constructed with ``profile=""``, storage resolves from that profile's own HERMES_HOME using the same legacy/consolidated layout rules as ``hermes -p pairing ...``. This keeps multiplex gateways and profile-scoped CLI approvals on one whitelist. Without a profile, storage is the global pairing directory for the current HERMES_HOME. NprofilecR|r6t}|dkr|n|dz |z }tdd||_n t|_|jdd|rt ||jnt t j|_||_ dS) Ndefaultprofilesrr)rTrr) rr_dirrrr threadingRLock_lock_profile)selfrroot profile_homes rC__init__zPairingStore.__init__s  $*,,Di''J&0  '#!DII $DI t444  * (\$) L L L L L ( ) ) )_&&  rLr6c|jS)zCProfile name this store is scoped to, or None for the global store.)rrs rCrzPairingStore.profiles }rLr5c|j|dz S)Nz -pending.jsonrrr5s rC _pending_pathzPairingStore._pending_pathsyh55555rLc|j|dz S)Nz-approved.jsonrrs rC_approved_pathzPairingStore._approved_pathsyh66666rLc|jdz S)Nz_rate_limits.jsonrrs rC_rate_limit_pathzPairingStore._rate_limit_pathsy...rLrc|r tj|dS#t$r} |}d|jdt|jdd}n#t$rd}YnwxYwttdrtj nd}td ||||icYd}~Sd}~wtjtf$ricYSwxYwiS) Nrrz owner_uid=z mode=z geteuidzn/aa)Pairing file %s exists but is not readable as uid=%s (%s; %s). If you ran `docker exec hermes pairing approve ...` as root, re-run with `docker exec -u hermes ...` and chown the existing file to the hermes user, or restart the container so the entrypoint can fix ownership.)rrrrPermissionErrorstatst_uidoctst_moderrrirloggerwarningr)rrest owner_infoeuids rC _load_jsonzPairingStore._load_jsons4 ;;==  z$..'."B"BCCC"   1B!Ubi!U!Us2:rss?S!U!UJJ111!0JJJ1(/r9'='=Hrz|||5E $ A  ('2      s@'> D ;BC& BC&BA C& D&DDrcPt|tj|dddS)NrFr)rrr)rrrs rC _save_jsonzPairingStore._save_jsons)dDJtAEJJJKKKKKrLrRc"t||S)zHH tt urLcg}|r|gn|d}|D]^}|||}|D]\}}|||d| _|S)z5List approved users, optionally filtered by platform.r)r5rR)_all_platformsr ritemsro)rr5resultsrprrJinfos rC list_approvedzPairingStore.list_approved s"*OXJJ0C0CJ0O0O  H HAt':':1'='=>>H%^^-- H H TA#FFFGGGG HrLr8 user_namec\}|fd|D}|D]}||=|tjd|<|t dS)zAAdd a user to the approved list. Must be called under self._lock.cBg|]}||SrHr)rIrnormalized_user_idr5rs rCrKz.PairingStore._approve_user..sC    ##H.>@RSS    rL)r approved_atN)r rrVtimerrt)rr5rRrr duplicate_idsrr"s`` @rC _approve_userzPairingStore._approve_users??4#6#6x#@#@AA!44XwGG      $,   !. + + )**#9;;( ( #$ ++H55x@@@ H&899999rLc<}j5|}fd|D}|r<|D]}||=||t  ddddS dddn #1swxYwYdS)z.2sB$''2BGLL rLNTF)rrr rr)rr5rRrr matching_idsrs``` rCrevokezPairingStore.revoke-s;""8,, Z  t,,H(0L  (433$ !122h///'x999                         usABBBcodesaltcztj||dzS)z6Hash a pairing code with the given salt using SHA-256.r)hashlibsha256encode hexdigest)r+r,s rC _hash_codezPairingStore._hash_codeDs1~dT[[%9%99::DDFFFrLpending matched_key matched_entryc$||=|||||||||d|dd|d|dddS)zDRemove a pending request and approve its user. Must hold self._lock.rRrr8)rRr)rr_reset_failed_attemptsr&r=)rr5r3r4r5s rC_finish_approvalzPairingStore._finish_approvalIs K  **844g>>> ##H---  mI. 0A0A+r0R0R   %Y/&**;;;   rLc|j5|||||}||r ddddS|||r ddddS|||}t|tkr ddddSd dttD}tj d}|||}tjd} ||||t%jd|| <||||||||cdddS#1swxYwYdS)a Generate a pairing code for a new user. Returns the code string, or None if: - User is rate-limited (too recent request) - Max pending codes reached for this platform - User/platform is in lockout due to failed attempts The code is NOT stored in plaintext. Only a salted SHA-256 hash is persisted so that reading the pending file does not reveal codes. Nr8c3HK|]}tjtVdSN)secretschoiceALPHABET)rI_s rC z-PairingStore.generate_code..s,PP7>(33PPPPPPrLr )hashr,rRr created_at)r_cleanup_expiredrV_is_locked_out_is_rate_limitedr rrMAX_PENDING_PER_PLATFORMrqrange CODE_LENGTHriurandomr2r< token_hexhexr$r_record_rate_limit) rr5rRrr"r3r+r, code_hashentry_ids rC generate_codezPairingStore.generate_codeasNZ( (   ! !( + + +!%!8!87!K!K ""8,,  ( ( ( ( ( ( ( ( $$Xw77 ( ( ( ( ( ( ( ( ood&8&8&B&BCCG7||777( ( ( ( ( ( ( ( $77PPU;=O=OPPPPPD:b>>Dd33I(++H" -&"ikk !!GH  OOD..x88' B B B  # #Hg 6 6 6Q( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( s&AF3F3;AF3 CF33F7:F7c|j5|||}||r ddddS|||}d}d}|D]\}}t|tsd|vsd|vr$ t |d}n#t$rYRwxYw| ||} tj| |dr|}|}n|#|| ddddS|||||cdddS#1swxYwYdS)u Approve a pairing code. Adds the user to the approved list. Returns ``{user_id, user_name}`` on success, ``None`` if the code is invalid/expired OR the platform is currently locked out after ``MAX_FAILED_ATTEMPTS`` failed approvals (#10195). Callers can disambiguate with ``_is_locked_out(platform)``. Verification: the user-provided code is hashed with each stored entry's salt and compared to the stored hash using constant-time comparison. Pre-hash entries (legacy plaintext-key format from pre-upgrade pending.json files) are silently ignored — they get pruned at TTL by ``_cleanup_expired``. Nr,rB)rrDupperr;rEr rrrrbytesfromhex ValueErrorr2r<compare_digest_record_failed_attemptr8) rr5r+r3r4r5rOrBr,candidate_hashs rC approve_codezPairingStore.approve_codesXZ) X) X  ! !( + + +::<<%%''D""8,, ) X) X) X) X) X) X) X) Xood&8&8&B&BCCGK M#*==??  %!%..&&&*=*= ==v77DD!H!%t!'A$E> C-,E>- C:7E>9C::AE>E>>FFrct|pd}t|dkotd|DS)avTrue when ``value`` has the shape of a ``list_pending`` request id. Request ids are ``secrets.token_hex(8)`` (16 lowercase hex chars); pairing codes are 8 chars from an unambiguous uppercase alphabet that excludes every hex letter's ambiguity partner. The two shapes cannot collide, so callers accepting either can dispatch on this. r8rAc3K|]}|dvV dS)0123456789abcdefABCDEFNrH)rIcs rCr@z5PairingStore.looks_like_request_id..s('U'U!-E(E'U'U'U'U'U'UrL)rTr;rall)rs rClooks_like_request_idz"PairingStore.looks_like_request_idsNEKR  &&((5zzRUC'U'Uu'U'U'U$U$UUrL request_idcr|j5||t|pd}|s ddddS|||}|D]~\}}t|tsd|vsd|vr$tj t||r&| ||||ccdddS ddddS#1swxYwYdS)a Approve a pending pairing request by its server-side request id. This is the grant path for authenticated admin surfaces (``hermes pairing list``, the dashboard/desktop approve buttons), which show pending requests but must never reveal the one-time code DM'd to the user. Returns ``{user_id, user_name}`` on success, ``None`` for an unknown/expired request id. Unlike :meth:`approve_code` this does NOT count a miss toward the brute-force lockout, and is not itself gated by one. The lockout protects the 8-char code space against guessing over a messaging channel; a request id is only ever obtained by an admin already authenticated to this store, so a stale id means "the row you clicked expired", not an attack. Counting it here let a few GUI clicks on a stale list lock the operator out of the CLI's code path too. r8Nr,rB) rrDrTr;r:r rrrrr<rVr8)rr5r`r3rOrBs rCapprove_requestzPairingStore.approve_requests$Z    ! !( + + +Z-2..4466<<>>J           ood&8&8&B&BCCG#*==?? U U%!%..&&&*=*=)#h--*=*=*?*?LLU007HeTTTT        U                  sAD,#B-D,D,,D03D0c bg}|j5|r|gn|d}|D]n}|||||}|D]\}}t |ts|d}t |ttfsNttj |z dz } t |dto't |dt} | || rt|nd|dd|dd| d p d d d n #1swxYwY|S) uzList pending pairing requests, optionally filtered by platform. Codes are stored hashed and are never returned. Each entry exposes a server-side ``request_id`` that an authenticated admin surface passes to :meth:`approve_request`. Legacy pre-hash entries have no approvable id — they report an empty ``request_id`` and age out at TTL. r3rC<rBr,r8rRr)r5r`rRr age_minutesN)rrrDr rrrrr=intfloatr$rTro) rr5rrrr3rOrrCage_min is_moderns rC list_pendingzPairingStore.list_pendings Z  &.R D4G4G 4R4RI  %%a(((//$*<*%>'. $$                ,sF F$$F(+F(cN|j5d}|r|gn|d}|D]e}|||}|t |z }|||if dddn #1swxYwY|S)z2Clear all pending requests. Returns count removed.rr3N)rrr rrr)rr5countrrr3s rC clear_pendingzPairingStore.clear_pending#s Z ; ;E&.R D4G4G 4R4RI ; ;//$*<*>*;f*;*;*;R@@**3///$$X...rLr;)r8),__name__ __module__ __qualname____doc__rrTrpropertyrrrrrrr rrVrXr\rardrrrr&r* staticmethodrSr2r8rPrYr_rbrjrfrmrFrMrErWr7rDrrHrLrCrrs         @#X6c6d66667s7t7777/$////t@LtL4LDLLLL5355555533s3s3x33336636s6t6666 C#$cT::c:C:C:QU::::.sST.GGEGcGGG\G  &* 9< MQ     2=?666&)6696 #6666p8XS8X8X8X8X8X8Xt VS VT V V V\ V!!!$!!!!FSDB  c S    st93999999+s+t++++ 9s 9t 9 9 9 9 =s =t = = = =++++++4STrLr)9rr.rloggingrir<rrr$pathlibrtypingrgateway.whatsapp_identityrrhermes_constantsrrr utilsr getLoggerrrr>rIrrprrGr~rr<rTrDrrOrarQrVrXr\rdrkrtrrrrrrrrrrrrHrLrCrs!(    !  8 $ $ . n0)<< ( &(4   "   $  " , $( $ "4 $ .!" #$&%,#(3-*B#B$BBBBNsNtNNNN ss s S SX    ScSSSSTSSSS......4 #      :*+s++++c4#>#;S#;3#;4#;#;#;#;L$4R4RRRRRR8 ! * * * 4. * TN * * * * *CD4ttttttttttrL