> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Crypto — crittografia AT Protocol

> Il modulo Crypto del pacchetto Laravel Bluesky. Illustra le coppie di chiavi P-256 / secp256k1, le DID key, JWT, DPoP e la conversione delle firme.

<Warning>
  Crypto è un'implementazione interna avanzata. Non è necessario per le operazioni comuni come post, recupero feed o notifiche. Consultalo quando devi costruire verifica firma di basso livello o implementazioni OAuth per AT Protocol.
</Warning>

## Panoramica della crittografia in AT Protocol

AT Protocol adotta la crittografia a curva ellittica (ECC) in modo esteso per realizzare una rete sociale decentralizzata. Gli usi principali sono i seguenti.

```mermaid theme={null}
graph TD
    A["Coppia di chiavi<br>(P-256 / secp256k1)"] --> B["Firma con chiave privata"]
    A --> C["Codifica della chiave pubblica in did:key"]
    B --> D["Token DPoP (OAuth)"]
    B --> E["Firma dei commit (repository)"]
    B --> F["Firma delle label (Labeler)"]
    C --> G["Registrazione nel DID Document"]
    G --> H["Verifica della firma con la chiave pubblica"]
```

| Curva             | Algoritmo | Uso principale                             |
| ----------------- | --------- | ------------------------------------------ |
| secp256r1 (P-256) | ES256     | OAuth (DPoP, Client Assertion)             |
| secp256k1 (K256)  | ES256K    | Verifica firma di Feed Generator e Labeler |

***

## Classi delle coppie di chiavi

### AbstractKeypair

`AbstractKeypair` è la classe base comune per P256 / K256. Internamente utilizza [phpseclib3](https://phpseclib.com/).

```php theme={null}
// Genera una nuova coppia di chiavi
$keypair = P256::create();
$keypair = K256::create();

// Carica da una chiave privata codificata in Base64 URL-safe
$keypair = P256::load($base64PrivateKey);

// Ottieni in formato PEM
$privatePem = $keypair->privatePEM();
$publicPem  = $keypair->publicPEM();

// Converti in JWK (JSON Web Key)
$jwk = $keypair->toJWK();
```

### P256 (secp256r1)

```php theme={null}
use Revolution\Bluesky\Crypto\P256;

$keypair = P256::create();
```

Utilizzata in OAuth (DPoP / Client Assertion). `OAuthKey` estende P256 e carica la chiave privata da `config('bluesky.oauth.private_key')`.

È disponibile anche un comando Artisan per generare una nuova chiave privata OAuth.

```bash theme={null}
php artisan bluesky:new-private-key
```

### K256 (secp256k1)

```php theme={null}
use Revolution\Bluesky\Crypto\K256;

$keypair = K256::create();
```

Utilizzata per l'autenticazione di Feed Generator e Labeler. PDS / Relay di Bluesky verificano la firma su questa curva.

***

## DidKey

La classe `DidKey` codifica e decodifica una chiave pubblica nel formato `did:key`.

### Cos'è il formato did:key

In AT Protocol una chiave pubblica è rappresentata come stringa `did:key:z...`. È l'aggiunta di un identificatore di curva alla chiave pubblica, seguita da una codifica multibase in Base58btc.

```mermaid theme={null}
graph LR
    A["Chiave pubblica (PEM)"] --> B["Identificatore curva + chiave pubblica compressa"]
    B --> C["Codifica Base58btc"]
    C --> D["did:key:z..."]
```

### Codifica di una chiave pubblica in did:key

```php theme={null}
use Revolution\Bluesky\Crypto\DidKey;
use Revolution\Bluesky\Crypto\K256;

$keypair = K256::create();
$publicPem = $keypair->publicPEM();

// Converti nel formato did:key
$didKey = DidKey::format($publicPem);
// => "did:key:zQ3s..."
```

### Parsing della chiave pubblica dal DID Document

```php theme={null}
use Revolution\Bluesky\Crypto\DidKey;
use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Support\DidDocument;

$didDoc = DidDocument::make(
    Bluesky::identity()->resolveDID('did:plc:***')->json()
);

// Genera un oggetto chiave pubblica di phpseclib3 dal publicKey (multibase) del DID Document
$publicKey = DidKey::parse($didDoc->publicKey());
```

***

## JsonWebToken (JWT)

La classe `JsonWebToken` fornisce codifica e decodifica di JWT.

```php theme={null}
use Revolution\Bluesky\Crypto\JsonWebToken;

// Genera un JWT (firmato con la chiave privata PEM)
$token = JsonWebToken::encode(
    payload: ['iss' => 'did:plc:***', 'aud' => 'https://bsky.social', 'exp' => time() + 60],
    key: $privatePem,
    alg: 'ES256',
);

// Decodifica il JWT (senza verifica della firma)
$payload = JsonWebToken::decode($token);
```

***

## DPoP (Demonstrated Proof of Possession)

DPoP è un meccanismo di sicurezza che lega un access token OAuth a una specifica coppia di chiavi del client. Previene gli attacchi di replay del token.

```mermaid theme={null}
sequenceDiagram
    participant App as App Laravel
    participant AS as Authorization Server
    participant RS as Resource Server

    App->>AS: Richiesta PAR (+ header DPoP)
    AS-->>App: request_uri
    App->>AS: Richiesta token (+ header DPoP)
    AS-->>App: Access token (DPoP bound)
    App->>RS: Richiesta API (+ header DPoP + ath)
    RS-->>App: Risposta
```

La classe `DPoP` è utilizzata internamente e normalmente non serve invocarla direttamente. Il middleware `OAuthAgent` applica automaticamente gli header DPoP.

```php theme={null}
// Generazione della proof DPoP (per richiesta di token OAuth)
$proof = DPoP::authProof(
    jwk: $jsonWebKey,
    url: 'https://bsky.social/oauth/token',
    method: 'POST',
    nonce: $nonce,
);

// Generazione della proof DPoP (per richiesta API, include ath)
$proof = DPoP::apiProof(
    jwk: $jsonWebKey,
    url: 'https://api.bsky.app/xrpc/...',
    method: 'GET',
    token: $accessToken,
    nonce: $nonce,
);
```

***

## Signature (conversione formato firma)

AT Protocol utilizza il formato di firma compatto a 64 byte, mentre phpseclib3 restituisce firme in formato ASN.1 DER. La classe `Signature` gestisce questa conversione.

```php theme={null}
use Revolution\Bluesky\Crypto\Signature;

// ASN.1 DER → compatto (64 byte)
$compact = Signature::toCompact($derSignature);

// Compatto → ASN.1 DER
$der = Signature::fromCompact($compactSignature);
```

***

## JsonWebKey

`JsonWebKey` è la classe che rappresenta una JWK (JSON Web Key). Viene usata nella generazione delle proof DPoP.

```php theme={null}
use Revolution\Bluesky\Crypto\JsonWebKey;

// Genera una JWK da una coppia di chiavi
$jwk = $keypair->toJWK();

// Oppure istanzia direttamente
$jwk = JsonWebKey::load(['kty' => 'EC', 'crv' => 'P-256', ...]);
```

***

## OAuthKey

`OAuthKey` è una classe di chiave dedicata a OAuth che estende P256 e usa il valore di `config('bluesky.oauth.private_key')` come chiave privata.

```php theme={null}
use Revolution\Bluesky\Crypto\OAuthKey;

// Carica la chiave privata dalla configurazione
$oauthKey = OAuthKey::load();

// Utilizzata per firmare il JWT di Client Assertion
$jwk = $oauthKey->toJWK();
```

Normalmente viene gestita automaticamente all'interno di Bluesky Socialite.

***

## Link di riferimento

* [AT Protocol: Identity](https://atproto.com/guides/identity)
* [AT Protocol: Cryptography spec](https://atproto.com/specs/cryptography)
* [phpseclib3](https://phpseclib.com/)

<Info>
  Source: [src/Crypto/](https://github.com/invokable/laravel-bluesky/tree/main/src/Crypto)
</Info>


## Related topics

- [Core — operazioni core di AT Protocol](/it/packages/laravel-bluesky/core.md)
- [Tutorial - Laravel Console Starter](/it/packages/laravel-console-starter/tutorial.md)
- [Laravel LSP — estensione delle funzionalità IDE tramite Language Server Protocol](/it/blog/laravel-lsp-introduction.md)
- [Laravel Console Starter](/it/packages/laravel-console-starter/index.md)
- [Tutorial per bot - Laravel Bluesky](/it/packages/laravel-bluesky/bot-tutorial.md)