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.

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.

​

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.

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 utilisé par AT Protocol. Elle prend en charge les liens CID (tag 42) en extension du CBOR standard.

​

Encoder

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

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).

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.

​

CIDv0 et CIDv1

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

​

API principale

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.

​

Décodage

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.

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

---

​

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

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

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.

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.

// 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
• AT Protocol: CID spec
• IPLD: DAG-CBOR spec

Source : src/Core/