at_commons #

Foundational types used across every package in the Atsign Protocol SDK: key representations, metadata, atSign validation, root-domain parsing, verb builders (Atsign Protocol wire format), and the exception hierarchy.

at_commons is a pure-Dart library with no dependency on any specific client implementation. Most application developers consume these types transitively via at_client; you'll reach for at_commons directly when you need to construct an AtKey by hand, interpret exceptions, or build Atsign Protocol verbs at a lower level.

AtKey #

AtKey represents a key in the atServer keystore. Prefer the static factory methods over the field-builder form — they encode the key shape (self / shared / public / local / cached) at the type level:

// Shared with another atSign
AtKey shared = (AtKey.shared('phone', namespace: 'myapp', sharedBy: '@alice')
      ..sharedWith('@bob'))
    .build();

// Public (readable by anyone)
AtKey pub = AtKey.public('avatar', namespace: 'myapp', sharedBy: '@alice').build();

// Self (only readable by the owner)
AtKey self = AtKey.self('prefs', namespace: 'myapp', sharedBy: '@alice').build();

// Local (never synced to the cloud)
AtKey local = AtKey.local('cache', '@alice', namespace: 'myapp').build();

// Parse from a wire-format string
AtKey parsed = AtKey.fromString('@bob:phone.myapp@alice');

Useful getters:

Metadata #

Metadata carries per-key settings. The fields most app code actually touches:

Atsign / AtRootDomain #

Atsign alice = '@alice'.toAtsign();          // validated, fully qualified
AtsignWithoutAt a = alice.withoutAt;         // no leading '@'

AtRootDomain root = AtRootDomain.parse('root.atsign.org:64');
AtRootDomain prod = AtRootDomain.atsignDomain; // production default

Exceptions #

All exceptions extend AtException. The main sub-hierarchies are:

• AtConnectException — connection / auth failures (SecondaryServerConnectivityException, UnAuthorizedException, HandShakeException, …)
• AtServerException — server-side errors (InboundConnectionLimitException, LookupException, InternalServerException, …)
• AtEnrollmentException — APKAM enrollment failures (AtInvalidEnrollmentException, AtEnrollmentRevokeException, AtThrottleLimitExceeded)
• Standalone: InvalidAtKeyException, KeyNotFoundException, AtTimeoutException, InvalidAtSignException, AtSigningException, AtIOException, and others.

Verb builders #

Each builder constructs an Atsign Protocol wire command via buildCommand(). Application code normally doesn't touch these directly — the client packages use them internally — but they're exposed for lower-level tooling (see the test suite in test/ for concrete usage).

Other types #

• AtBytes — wrapper for base64-encoded binary payloads
• KeyType — selfKey, sharedKey, publicKey, localKey, cachedSharedKey, …
• EnrollmentStatus — pending, approved, denied, revoked, expired
• PublicKeyHash — hash + algorithm of a public encryption key
• SecureSocketConfig — TLS configuration for atServer connections

Where to go next #

• at_client — the client that uses these types
• at_auth — onboarding / authentication that produces the keys embedded in AtKey