at_client_sdk

The main repository for libraries used to build applications on the Atsign Platform. Three categories: SDKs, libraries, and Flutter widgets.

SDKs

An app depends on its one platform package and imports only that; the SDK shape explains the layers.

• at_client_cli: the platform package for every native Dart program that isn’t Flutter — command-line tools, daemons, servers and IoT devices. CLIBase turns a program’s flags into an online AtClient, CliKeys keeps its keyfile and store, and the at_activate and at_register tools register, activate and enrol atSigns.
• at_client_flutter: the platform package for Flutter apps on mobile and desktop. Adds onboarding and authentication dialogs and device-keychain storage. Flutter web is not a supported target.
• at_client: the platform-neutral core both re-export. Owns the whole atSign lifecycle — Atsign('@alice').open, .activate and .enroll hand back an AtClient — as well as collections, sync, notifications and encryption. A program imports it directly only when it supplies every dependency itself.

Libraries

Dart libraries for building Atsign Platform applications. All are published on pub.dev.

• at_auth: the protocol layer under at_client’s lifecycle verbs: CRAM activation, the APKAM enrollment handshakes, the .atKeys key stores and the registrar client. Applications reach it through at_client.
• at_chops: cryptographic and hashing operations (encryption, decryption, signing, hashing) used by the rest of the SDK, including the post-quantum primitives.
• at_cli_commons: deprecated; a re-export of at_client_cli, which carries CLIBase.
• at_commons: foundational types used across every package: keys, metadata, atSign validation, root-domain parsing, verb builders for the Atsign Protocol wire format, and the exception hierarchy.
• at_contact: contacts library that persists across different Atsign Platform applications.
• at_lookup: low-level direct implementation of the Atsign Protocol verbs. Used by at_client and at_client_flutter.
• at_onboarding_cli: deprecated; a re-export of at_client_cli, which carries the at_register and at_activate tools.
• at_policy: scaffolding for building policy-management services that talk to enforcement endpoints via the Atsign Protocol.
• at_telemetry: telemetry for apps and atServers: the record model, the OTLP/JSON logs encoding, and a client that sends an app’s telemetry to a collector atSign. Experimental, below 1.0.
• at_utils: utility library: atSign, metadata, configuration, logger.
• base2e15: fork of the upstream base2e15 package, kept here for null-safety support.
• dart_utf7: fork of the upstream utf7 package, kept here for null-safety support.

Flutter packages

Status: Most of the at_*_flutter packages listed below are in the process of being deprecated. Over the next few months they’ll be replaced by example application code rather than reusable widget packages. The recommended path for new Flutter work is to read the example app at packages/at_client_flutter/example/todos and adapt it directly. The packages will continue to publish until that migration completes.

• at_backupkey_flutter: deprecated; export the keys with FileAtKeysIo as the at_client_flutter README shows.
• at_chat_flutter: chat feature using atSigns and the Atsign Protocol.
• at_common_flutter: common widgets used by other Atsign Flutter packages. Already deprecated in favour of at_client_flutter.
• at_contacts_flutter: contact-management widgets for atSign-based apps.
• at_contacts_group_flutter: group functionality on top of at_contacts_flutter.
• at_events_flutter: event management.
• at_follows_flutter: a basic social “follows” feature for atSigns.
• at_invitation_flutter: deprecated; invitations are now AtClientInvitations in at_client, shown in the at_client_flutter invitations example.
• at_location_flutter: share location between two atSigns and view on OpenStreetMap.
• at_login_flutter: zero-trust logins using the Atsign Protocol.
• at_notify_flutter: notification surface.
• at_sync_ui_flutter: UI indicator for the SDK’s sync process.
• at_theme_flutter: theme switching.

Post-quantum cryptography

The SDK can protect everything an adversary could record today — data shared between atSigns, an atSign’s own data, and the secrets an enrollment approval hands a new device — with post-quantum key establishment, and can authenticate with a post-quantum signature. It is opt-in per client, through one setting:

final preference = AtClientPreference(posture: PqPosture.pqActive)
  ..namespace = 'todos';

A new app names pqActive. An app built on 3.x moves in two steps: rebuild it with pqReady and roll that out, then rebuild it with pqActive and roll that out.

Under the hood, each namespace an atSign owns gets a key-establishment keypair — the X-Wing hybrid (ML-KEM-768 + X25519) by default, pure ML-KEM-1024 on request — published as a signed advertisement; a writer establishes a content key to the recipient’s namespace key and encrypts the record with AES-256-GCM, and a sender follows whatever the recipient advertised. An enrollment submitted under a post-quantum posture advertises a key package, and the approving client seals the atSign’s secrets to it rather than wrapping them with RSA. A client whose posture asks for a stronger authentication key than its enrollment holds re-enrolls itself at its first start, filing the new enrollment in the same keys store beside the legacy fields. ML-DSA authentication needs an atServer that verifies it; a legacy client makes no such demand unless its key material raises it to a floor.

The default posture moves one stage at a time — legacy through 4.0, pqReady from a later 4.x release, pqActive at 5.0 — because a record may only be written in a scheme every reader of it supports, so the stage that reads post-quantum data rolls out before the stage that writes it by default. An app names pqReady or pqActive to move first.

The developer’s view, the goals and the ladder are in the at_client README; the design is under docs/projects/pq/.

Upgrading

at_client 4.0 is a major release, and so is each platform package: an app moves to at_client_cli 1.0 or at_client_flutter 2.0, imports only that, and names its client’s storage. Upgrading to at_client 4.0 takes it error by error, with a checklist for each path.

Installation

Each package’s own README and pub.dev page have the installation details. Click any of the links above.

AI Agent Skill

The at_client_skills package gives AI agents accurate, up-to-date knowledge of at_client and at_client_flutter — covering AtCollection, auth flows, querying, sub-collections, testing patterns, and common pitfalls.

# Add to your project
dart pub add --dev at_client_skills skills

# Install the skill into your IDE
dart run skills get

Works with Claude Code, Cursor, GitHub Copilot, Cline, and any agent supporting the agentskills.io specification.

Maintainers

Atsign Foundation core devs

Appendix: why a posture is a floor

A posture only ever moves a client up. A preference cannot name an authentication key weaker than its posture names, and a client never gives up a stronger key it already holds, whatever posture it is later built with.

A client’s own keyfile sets a floor too: a namespace key’s private sets pqReady, and an active ML-DSA-65 data signing key sets pqActive. A client configured below that floor runs at the floor and logs a warning saying what was raised. It is not refused, because everything that names no posture runs at the default, legacy: AtClientPreference(), CLIBase, at_activate, and any tool or service that opens a keyfile without naming one. A refusal would stop exactly those, often a tool opening a keyfile that an app has already moved up, while a raised client loses nothing it cannot get back.

A raised client never seeds namespace keys or mints the atSign’s signing root unless its own posture would have. Each is a permanent record for the atSign, and a floor never creates one the client was not configured to create.

4.0 keeps legacy as the default. With pqActive as the default, every tool that names no posture would upgrade whatever keyfile it opened, refuse writes to peers that publish no namespace key, and onboard keyfiles that releases before 4.0 cannot read.

The default moves as the ladder says: pqReady from a later 4.x release, then pqActive at 5.0. From 5.0, a client explicitly configured below its floor is planned to be refused rather than raised. A 4.x release may add that refusal as an opt-in for deployments that want it sooner.