Obmedzené tokeny a inštalácie

Inštalačný token bez obmedzenia má hodinu prístup ku každému repozitáru, kde je aplikácia nainštalovaná. Obmedzte ho preto na konkrétnu operáciu — práve na to slúži vydávanie tokenov namiesto ich ukladania:

use RoundlyConsulting\Git\Dto\Credentials\GithubAppToken;
use RoundlyConsulting\Git\Dto\Input\InstallationTokenScope;

$scoped = GithubAppToken::for(appId: $id, installationId: $installation, privateKey: $key)
    ->forScope(InstallationTokenScope::forRepositories(repositoryIds: ['40823311']));

Git::github($scoped)->repo('acme/api')->cloneUrl('acme', $scoped);

// Or select by name — equally narrow:
InstallationTokenScope::forRepositories(repositories: ['acme/api', 'acme/web']);

• forRepositories() berie sadu oprávnení z git.providers.github.app.permissions, takže sa miesta volania nemôžu odchýliť od toho, čo aplikácia skutočne dostala.
• repositoryIds (číselné, prežije premenovanie) a repositories (názvy) obmedzujú rovnako úzko; nečíselné id vyhodí InvalidCredentialsException.
• forScope() vráti nové prihlasovacie údaje — pôvodné sa nikdy potajomky nezúžia niekomu inému.
• Cache tokenov je rozdelená podľa rozsahu, takže obmedzené vydanie nikdy nedostane širší token z cache.

Zámerne široké rozsahy

Prázdny rozsah balík rovno odmietne — rozsah bez jediného repozitára by vydal token pre všetky repozitáre inštalácie, preto radšej vyhodí výnimku, než by ho potichu rozšíril. Dve operácie repozitár pomenovať skutočne nevedia a každá má rozsah taký široký, aký musí byť, a taký slabý, aký môže byť:

• InstallationTokenScope::metadataOnly() — všetky repozitáre, len metadata: read. Použite ho na zistenie, ktoré repozitáre inštalácia má.
• InstallationTokenScope::administrationOnly() — všetky repozitáre, len administration: write. Použite ho na vytvorenie repozitára, vydajte ho až v momente potreby a nikdy ho neukladajte, nelogujte ani neposúvajte ďalej.

Git::github($credentials->forScope(InstallationTokenScope::metadataOnly()))
    ->installationRepositories();          // Page<Repository>

Git::github($credentials->forScope(InstallationTokenScope::metadataOnly()))
    ->allInstallationRepositories();       // LazyCollection<Repository>

Bez akéhokoľvek rozsahu dostanete všetko, čo inštalácia povolila, všade — takmer nikdy to nechcete. Rozsah, ktorý inštalácia nevie splniť (neznámy repozitár, nepovolené oprávnenie), ako aj zaniknutá inštalácia vyvolajú InvalidCredentialsException; 403 (limit, pozastavenie) zostáva RequestException, pretože to prvé aplikácie chápu ako potrebu znovu prepojiť účet.

Konanie v mene aplikácie

Endpointy /app/** sa prihlasujú vlastným JWT aplikácie, nie inštalačným tokenom — takto overíte id inštalácie skôr, než mu uveríte, napríklad keď prišlo z presmerovania v prehliadači. Git::githubApp() číta git.providers.github.app.id a private_key a ak niektorý chýba, vyhodí InvalidCredentialsException s jeho názvom:

$installation = Git::githubApp()->installations()->find($installationIdFromTheRedirect);

$installation->accountLogin;            // "acme-inc"
$installation->accountType;             // e.g. "Organization"
$installation->repositorySelection;     // "all" | "selected"
$installation->permissions;             // ['contents' => 'write', ...]
$installation->reachesEveryRepository();
$installation->isSuspended();

Git::github($credentials)->installationRepositories(); // NOT /user/repos: an
                                                       // installation token 403s there

Ďalšie vyhľadávania cez JWT aplikácie — všetky účty, kde je aplikácia nainštalovaná, a nájdenie inštalácie podľa účtu namiesto id (užitočné, keď zákazník aplikáciu preinštaluje a uložené id zastará):

$installations = Git::githubApp()->installations();

$installations->all();                       // Page<Installation>
$installations->forOrganization('acme-inc'); // Installation
$installations->forUser('jane-doe');         // Installation

Endpointy /app/** vyžadujú údaje aplikácie a inštalačné endpointy údaje inštalácie; pri zámene balík vyhodí vlastnú InvalidCredentialsException namiesto nejasného 403 od GitHubu. Všetky tieto metódy zavoláte na type Provider bez instanceof, dajú sa ovládať cez Git::fake() a na GitLabe a Bitbuckete vyhodia FeatureNotSupportedException.

Inštalácia aplikácie

Používateľa pošlite nainštalovať aplikáciu cez installations()->installUrl() (vyžaduje app.slug). GitHub vráti state na Setup URL aplikácie spolu s installation_id, čím sa vracajúce sa presmerovanie spojí s požiadavkou, ktorá odišla:

$url = Git::githubApp()->installations()->installUrl($state); // https://github.com/apps/<slug>/installations/new?state=…