SDK Go

Le SDK Go fournit un client pour l’intégration avec l’API Subnoto. Il gère le chiffrement tunnel Oak, l’authentification par signature HTTP RFC 9421, et expose des services API typés générés à partir de la spécification OpenAPI.

Installation

Téléchargez l’archive correspondant à votre plateforme depuis la page des releases GitLab ou le GitLab Package Registry :

# Linux x86_64
curl -LO https://gitlab.com/api/v4/projects/75972071/packages/generic/subnoto-api-client-go/<VERSION>/subnoto-api-client-go-<VERSION>-linux-x86_64.tar.gz

# macOS arm64
curl -LO https://gitlab.com/api/v4/projects/75972071/packages/generic/subnoto-api-client-go/<VERSION>/subnoto-api-client-go-<VERSION>-darwin-aarch64.tar.gz

Remplacez <VERSION> par la dernière version publiée (par exemple 2.16.0).

Extrayez l’archive et ajoutez-la comme remplacement de module local dans votre go.mod :

mkdir -p third_party/subnoto-sdk
tar xzf subnoto-api-client-go-<VERSION>-linux-x86_64.tar.gz -C third_party/subnoto-sdk

require gitlab.com/subnoto/subnoto-monorepo-public/libs/api-client-go v0.0.0
replace gitlab.com/subnoto/subnoto-monorepo-public/libs/api-client-go => ./third_party/subnoto-sdk

L’archive contient les sources du SDK (subnoto/), le client OpenAPI généré (client/), les bindings de session Oak (oak_session_go/), la bibliothèque native précompilée (lib/liboak_session_go.so, .dylib sur macOS, ou .dll sur Windows), et go.mod.

Compilation

Les bindings de session Oak utilisent CGo et doivent être liés à la bibliothèque native :

SDK_DIR=./third_party/subnoto-sdk

CGO_LDFLAGS="-L${SDK_DIR}/lib -loak_session_go" \
go build ./...

À l’exécution, la bibliothèque native doit être accessible :

LD_LIBRARY_PATH=${SDK_DIR}/lib ./myapp       # Linux
DYLD_LIBRARY_PATH=${SDK_DIR}/lib ./myapp     # macOS

Sous Windows, copiez oak_session_go.dll à côté de votre exécutable ou ajoutez le répertoire lib\ à votre PATH. La DLL nécessite le Visual C++ Redistributable.

Démarrage rapide

Définissez vos identifiants comme variables d’environnement — SubnotoConfig les récupère automatiquement.

export SUBNOTO_ACCESS_KEY="votre-cle-acces"
export SUBNOTO_SECRET_KEY="votre-cle-secrete-hex"

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "gitlab.com/subnoto/subnoto-monorepo-public/libs/api-client-go/subnoto"
    oak "gitlab.com/subnoto/subnoto-monorepo-public/libs/api-client-go/oak_session_go"
)

func main() {
    factory := func(unattested bool, attesterKey []byte) (subnoto.OakSession, error) {
        var key *[]byte
        if attesterKey != nil {
            key = &attesterKey
        }
        return oak.NewOakClientSession(unattested, key)
    }

    client, err := subnoto.NewClient(&subnoto.SubnotoConfig{
        AccessKey: os.Getenv("SUBNOTO_ACCESS_KEY"),
        SecretKey: os.Getenv("SUBNOTO_SECRET_KEY"),
    }, factory)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    ctx := context.Background()
    whoami, _, err := client.Utils.PublicUtilsWhoamiPost(ctx).
        Body(map[string]interface{}{}).Execute()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Équipe : %s\n", whoami.GetTeamName())

    workspaces, _, err := client.Workspace.PublicWorkspaceListPost(ctx).
        Body(map[string]interface{}{}).Execute()
    if err != nil {
        log.Fatal(err)
    }
    for _, ws := range workspaces.GetWorkspaces() {
        fmt.Printf("Espace de travail : %s (%s)\n", ws.GetName(), ws.GetUuid())
    }
}

Configuration

Champ	Variable d’environnement	Description
`AccessKey`	`SUBNOTO_ACCESS_KEY`	Clé d’accès API depuis les paramètres de votre équipe
`SecretKey`	`SUBNOTO_SECRET_KEY`	Clé secrète API (encodée en hex) depuis les paramètres de votre équipe

Workspace et workspaceUuid

Dans la plupart des endpoints de l’API publique, workspaceUuid est facultatif. Lorsqu’il est omis, l’espace de travail par défaut de l’équipe est utilisé. Cela simplifie le code lorsque vous n’utilisez qu’un seul espace de travail. Pour cibler un espace de travail spécifique, passez workspaceUuid dans le corps de la requête.

Les détails par endpoint sont dans les spécifications OpenAPI.

Services API

Le SubnotoClient expose des services API typés sous forme de champs pour chaque groupe d’API :

Service	Champ	Description
Envelope	`client.Envelope`	Créer, envoyer, signer des enveloppes et gérer les documents
Workspace	`client.Workspace`	Lister et gérer les espaces de travail
Contact	`client.Contact`	Créer et gérer les contacts
Template	`client.Template`	Lister les modèles
Logs	`client.Logs`	Consulter les journaux d’audit
Authentication	`client.Authentication`	Créer des tokens iframe pour la signature intégrée
Webhook	`client.Webhook`	Gérer les webhooks
Utils	`client.Utils`	Endpoints utilitaires (whoami)

Vous pouvez aussi envoyer des requêtes JSON brutes avec client.Post("/public/utils/whoami", struct{}{}) lorsque vous n’avez pas besoin du client généré.

Gestion des erreurs

Les erreurs API sont retournées par les méthodes Execute() du client généré. Le SDK définit aussi SubnotoError pour des informations d’erreur structurées :

import "gitlab.com/subnoto/subnoto-monorepo-public/libs/api-client-go/subnoto"

// Les erreurs de Execute() incluent le statut HTTP et les détails du corps de réponse.
// SubnotoError fournit StatusCode et Message lorsque disponibles.
var _ *subnoto.SubnotoError

Chiffrement tunnel Oak

Le SDK Go utilise la bibliothèque native oak_session_go (bindings Go générés par UniFFI) pour établir un tunnel chiffré avec les enclaves AMD SEV-SNP de Subnoto. Cela garantit un chiffrement de bout en bout entre votre application et l’enclave, avec une attestation cryptographique que le serveur s’exécute dans une enclave sécurisée authentique.

Le tunnel est établi automatiquement lors de la création d’un SubnotoClient. La gestion de session, y compris la nouvelle tentative automatique en cas d’erreur de tunnel, est gérée de manière transparente par le transport tunnel.