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

# Core — opérations AT Protocol de base

> Module Core de Laravel Bluesky. Encodage CBOR, vérification de contenu par CID, manipulation des fichiers CAR et génération de clés d'enregistrement chronologiques via TID.

<Warning>
  Core est une implémentation interne avancée. Il n'est pas requis pour les opérations habituelles (publication, récupération de flux, notifications, etc.). Consultez cette page si vous manipulez directement les structures de données d'AT Protocol.
</Warning>

## Vue d'ensemble du modèle de données AT Protocol

Le dépôt AT Protocol adopte une structure de données adressée par contenu. Les éléments suivants sont utilisés pour le stockage, le transfert et la vérification des données.

```mermaid theme={null}
graph TD
    A["Données PHP (tableau)"] --> B["Encodage CBOR<br>(DAG-CBOR)"]
    B --> C["Hachage SHA-256"]
    C --> D["CID<br>(Content Identifier)"]
    D --> E["Fichier CAR<br>(ensemble de blocs)"]
    E --> F["Dépôt<br>(Merkle Search Tree)"]
```

| Classe   | Rôle                                             |
| -------- | ------------------------------------------------ |
| `CBOR`   | Sérialisation binaire                            |
| `CID`    | Adresse de contenu (identifiant par hachage)     |
| `CAR`    | Lecture/écriture d'archives de dépôt             |
| `TID`    | Clé d'enregistrement chronologique               |
| `Varint` | Encodage d'entier de longueur variable (interne) |

***

## CBOR

La classe `CBOR` fournit l'encodage et le décodage au format [DAG-CBOR](https://ipld.io/specs/codecs/dag-cbor/spec/) utilisé par AT Protocol. Elle prend en charge les liens CID (tag 42) en extension du CBOR standard.

### Encoder

```php theme={null}
use Revolution\Bluesky\Core\CBOR;

$record = [
    '$type'     => 'app.bsky.feed.post',
    'text'      => 'Hello, Bluesky!',
    'createdAt' => '2025-01-01T00:00:00.000Z',
];

$bytes = CBOR::encode($record); // Chaîne binaire
```

### Décoder

```php theme={null}
use Revolution\Bluesky\Core\CBOR;

// Décoder un seul élément
$data = CBOR::decode($bytes);

// Décoder le premier élément d'un flux et renvoyer le reste
[$item, $remainder] = CBOR::decodeFirst($bytes);

// Décoder tous les éléments d'un flux
$items = CBOR::decodeAll($bytes);
```

### Utilité

L'encodage CBOR est nécessaire pour calculer ou vérifier manuellement le CID d'un post (voir aussi la [page verify](/fr/packages/laravel-bluesky/verify)).

```php theme={null}
use Revolution\Bluesky\Core\CBOR;
use Revolution\Bluesky\Core\CID;

$record = data_get($block, 'value');
$cbor   = CBOR::encode($record);
$bool   = CID::verify($cbor, data_get($block, 'cid'));
```

***

## CID (Content Identifier)

Le CID est un identifiant auto-descriptif basé sur le hachage des données. Dans AT Protocol, le hachage SHA-256 est encapsulé dans un multihash, puis encodé en multicodec et multibase.

```mermaid theme={null}
graph LR
    A["Données (CBOR/Raw)"] --> B["SHA-256"]
    B --> C["multihash"]
    C --> D["multicodec<br>(dag-cbor / raw)"]
    D --> E["CIDv1<br>(base32 / base58btc)"]
```

### CIDv0 et CIDv1

| Version | Encodage  | Préfixe   | Usage                                    |
| ------- | --------- | --------- | ---------------------------------------- |
| v0      | base58btc | `Qm...`   | Ancienne spécification (blobs)           |
| v1      | base32    | `bafy...` | Nouvelle spécification (enregistrements) |

### API principale

```php theme={null}
use Revolution\Bluesky\Core\CID;

// Générer un CID à partir de données
$cid = CID::encode($data, CID::DAG_CBOR); // Pour les enregistrements
$cid = CID::encode($data, CID::RAW);      // Binaire (images, etc.)

// Vérifier un CID
$bool = CID::verify($data, $cid, CID::DAG_CBOR);
$bool = CID::verify($file, $cid, CID::RAW);

// Analyser un CID
$decoded = CID::decode($cid); // ['version', 'codec', 'hash']

// Obtenir la version d'un CID
$version = CID::version($cid); // 0 ou 1

// Conversion vers représentation en octets
$bytes = CID::decodeBytes($cid);
$cid   = CID::encodeBytes($bytes);
```

***

## CAR (Content Addressable aRchive)

Un fichier CAR est un format binaire qui contient un dépôt AT Protocol sous forme de séquence de blocs. Les données obtenues via `com.atproto.sync.getRepo` sont dans ce format.

```mermaid theme={null}
graph TD
    A["Fichier CAR"] --> B["En-tête<br>(CID racine)"]
    A --> C["Séquence de blocs"]
    C --> D["Signed Commit<br>(signature + CID prev)"]
    C --> E["Nœud MST"]
    C --> F["Enregistrement (CBOR)"]
```

### Décodage

```php theme={null}
use Revolution\Bluesky\Core\CAR;

// Décoder tout le fichier CAR (racine et tous les blocs)
['roots' => $roots, 'blocks' => $blocks] = CAR::decode($carData);

// Récupérer uniquement les CID racines
$roots = CAR::decodeRoots($carData);

// Itérer sur les blocs
foreach (CAR::blockIterator($carData) as [$cid, $block]) {
    // $cid : chaîne CID, $block : données binaires
}

// Récupérer sous forme de map d'enregistrements
foreach (CAR::blockMap($carData) as $key => $record) {
    // $key : clé de l'enregistrement, $record : tableau décodé
}
```

### Vérification d'un Signed Commit

Pour s'assurer qu'un fichier CAR appartient bien à l'utilisateur, vérifiez la signature du Signed Commit avec la clé publique du DID Document.

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

$did = 'did:plc:***';

$didDoc    = DidDocument::make(Bluesky::identity()->resolveDID($did)->json());
$publicKey = DidKey::parse($didDoc->publicKey());

$signed    = CAR::signedCommit($carData);
$bool      = CAR::verifySignedCommit($signed, $publicKey);
```

Exemple d'implémentation : [DownloadRepoCommand](https://github.com/invokable/laravel-bluesky/blob/main/src/Console/DownloadRepoCommand.php)

***

## TID (Timestamp Identifier)

Le TID est l'identifiant chronologique utilisé comme clé d'enregistrement dans AT Protocol. Il combine un horodatage en microsecondes et un identifiant d'horloge, encodés en base32 sur 13 caractères.

```
Exemple : 3jujm55ngfc24
```

### Génération et conversion

```php theme={null}
use Revolution\Bluesky\Core\TID;

// Générer le TID suivant
$tid = TID::next();
echo $tid->toString(); // Chaîne du type "3jujm55ngfc24"

// Créer un TID à partir d'une chaîne
$tid = TID::fromStr('3jujm55ngfc24');

// Créer à partir d'un timestamp (microsecondes) et d'un identifiant d'horloge
$tid = TID::fromTime(microtime(true) * 1000000, 0);
```

### Structure d'un TID

```mermaid theme={null}
graph LR
    A["Entier 63 bits"] --> B["53 bits : horodatage<br>(microsecondes)"]
    A --> C["10 bits : identifiant d'horloge"]
    B --> D["Encodage base32<br>(13 caractères)"]
    C --> D
```

`TID::s32encode()` et `TID::s32decode()` permettent la conversion entre entier et chaîne.

***

## Varint (entier de longueur variable)

`Varint` est un utilitaire interne utilisé pour l'analyse binaire CAR / CBOR. On ne l'utilise normalement pas directement.

```php theme={null}
use Revolution\Bluesky\Core\Varint;

// Encoder un entier
$bytes = Varint::encode(1234);

// Décoder depuis un flux (renvoie la valeur et le nombre d'octets consommés)
[$value, $bytesRead] = Varint::decodeStream($stream);
```

***

## À propos du mocking des fonctions Core

Les fonctions Core (CBOR/CID/CAR/TID) n'effectuent aucun accès externe et ne nécessitent donc pas de mock lors des tests.

```php theme={null}
// Peut être utilisé directement, y compris dans les tests
$bytes = CBOR::encode(['text' => 'Hello']);
$cid   = CID::encode($bytes, CID::DAG_CBOR);
$bool  = CID::verify($bytes, $cid);
```

***

## Liens utiles

* [AT Protocol: Repository spec](https://atproto.com/specs/repository)
* [AT Protocol: CID spec](https://atproto.com/specs/data-model#cid-formats)
* [IPLD: DAG-CBOR spec](https://ipld.io/specs/codecs/dag-cbor/spec/)

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


## Related topics

- [Tests de navigateur (Dusk)](/fr/dusk.md)
- [Crypto — chiffrement AT Protocol](/fr/packages/laravel-bluesky/crypto.md)
- [Tests](/fr/packages/laravel-bluesky/testing.md)
- [Migrations de base de données](/fr/migrations.md)
- [Client de base - Laravel Bluesky](/fr/packages/laravel-bluesky/basic-client.md)