at_auth library

The AtAuth package contains common logic for onboarding/authenticating an atSign to a secondary server

Classes

ApskSigningKey
One signing key read back out of an _apsk advertisement.
AtAuthSession
What a client is built from: the atSign, where its atServer is looked up, the key source, and the enrollment the keys authenticate as.
AtEnrollment
An abstract class for submitting and managing the enrollment requests.
AtEnrollmentRecord
Base class for enrollment-related data objects.
AtEnrollmentRequest
The EnrollmentRequest is used by the apps to submit enrollment request for APKAM keys which provides .atKeys specific to an application with restricted access to the namespaces. The application can access only the namespaces which are specified in the enrollment request. If the namespace has Read-Write access then the application is allowed to create/update the data, otherwise, if the namespace has only Read access then the application is allowed to read the data, but cannot create/update the data.
AtEnrollmentResponse
Represents the response of an enrollment operation received from the secondary server.
AtKeys
The in-memory model of an atsign's cryptographic keys.
AtKeysAssurance
Single home for all atKeys validation: low-level parsing/value checks (expect*/optional*, called by the models' fromJson) and cross-material structural invariants (validateKeyMaterials, validateAddKey, validateMapUpdate).
AtKeysEnrollment
What a keyfile records about one enrollment besides its keys — the snapshot an app reads to say which device a keyfile is for before authenticating, which the atServer cannot answer.
AtKeysIo
Base type for reading AtKeys. Implemented by classes that read AtKeys from different sources.
AtKeysPassphraseEnvelopeCodec
Encodes/decodes the passphrase envelope that optionally wraps an atKeys document at rest.
AtSelfEnrollmentRequest
An APKAM-authenticated self-enrollment: the request an already-enrolled client submits to spawn a FRESH enrollment for itself, which is the client half of the post-quantum retrofit. No OTP and no human approval: the connection's existing approved enrollment is the whole authority, and the atServer auto-approves a subset of its grants.
CryptographicMaterial
One cryptographic key material — e.g. the public half of an encryption keypair. This is the object app code interacts with everywhere in AtKeys's API (addKey, getKey, keysForKeyId, keysForEnrollment, retireKey); it is fully self-describing (keyId/enrollmentId included) so it never needs an owning wrapper to be meaningful on its own.
DeleteAtSignsResult
The result of RegistrarAdminService.deleteAtSigns.
DeleteTokenResult
The result of RegistrarAdminService.generateAtSignDeleteToken.
EnrollmentRequest
The BaseEnrollmentRequest class encapsulates shared fields between the InitialEnrollmentRequest and EnrollmentRequest.
EnrollmentRequestDecision
This class serves as the entity responsible for either approving or denying an enrollment request. The enrollment request is received through a notification from the server. The approving app has the authority to either grant or deny the request, with approval resulting in authentication and authorization to the requested namespaces.
FirstEnrollmentRequest
The FirstEnrollmentRequest represents an enrollment request when onboarding (activating) an atSign.
GeneratedAtKeysIo
An interface that defines methods for AtKeys that can be generated. It can be implemented by classes that generate AtKeys using different methods, such as secure element.
InMemoryAtKeysIo
Stores AtKeys in process memory.
NamespacePermission
Model class representing a namespace permission. The string representation of the permission is namespace: {ns1: rw, ns2: r} where read is r and write is w and ns1/ns2 are the namespaces.
RegisterAtSignResult
The result of Registrar.registerAtSign.
Registrar
RegistrarAdminService
The v4 /manage-atsigns/ delete flow, which requires a Super API key.
RegistrarService
RetryOptions
How an activation waits for a newly registered atSign to be provisioned.
WrittenAtKeysIo
An interface that defines methods for AtKeys that can be written. It can be implemented by classes that write AtKeys to different sources, such as file system or keychain.

Enums

EnrollmentKeyExchangeMode
How an enrollment's apkamSymmetricKey gets from one side to the other.
HttpMethod
RegisterOperation
What Registrar.registerAtSign asks the server to do: just check whether atSign is available, or check and activate it in the same call.
RegistrarApiEndpoint

Extension Types

CryptographicMaterialAlgorithm
Known values for CryptographicMaterial.algorithm — the algorithm family used by a key material, independent of its cryptographic role (see CryptographicMaterialRole).
CryptographicMaterialRole
Known values for CryptographicMaterial.role — the mechanical role a key material plays, independent of the algorithm family (see CryptographicMaterialAlgorithm).
CryptographicMaterialStatus
Whether a key material is in use, withdrawn, or gone.
KeyEntryStatus
Whether an advertised key entry is still offered for new operations.

Properties

retrofitSerializer ↔ RetrofitSerializer?
How a retrofit's read-mutate-write sequence is serialised, or null to run it unserialised.
getter/setter pair

Functions

activateAtSign({required String atSign, required String cramSecret, required WrittenAtKeysIo keys, required SigningAlgoType signingAlgo, AtRootDomain rootDomain = AtRootDomain.atsignDomain, String appName = 'firstApp', String deviceName = 'firstDevice', bool? mintLegacyMaterial, FutureOr<Map<String, dynamic>?> metadataBuilder(AtKeysIo keysIo)?, ({SigningAlgoType algorithm, String privateKey, String publicKey})? advertisedSigningKey, RetryOptions retryOptions = RetryOptions.defaultRetryOptions, bool completeActivation = true, void onProgress(ProgressEvent event)?, required AtLookupMuxable atLookUp, bool awaitProvisioning = false}) → Future<String>
Activates atSign with its one-time CRAM secret and writes the keys it mints into keys: the atSign's first enrollment, which the atServer grants everything.
apkamPossessionSignable({required String enrollmentId, required String apkamPublicKey, required String signingAlgo}) → String
What an enroll:update signs to prove the sender holds the private half of the APKAM public key it is asking the atServer to install: the enrollment id, the key and the algorithm, pipe-separated, signed as UTF-8.
apkamPossessionSignature({required String enrollmentId, required String apkamPublicKey, required String apkamPrivateKey, required SigningAlgoType signingAlgo}) → String
Base64 of apkamPossessionSignable, signed by apkamPrivateKey — what an enroll:update carries in EnrollVerbBuilder.apkamPublicKeySignature.
apskAdvertisement({required List<ApskSigningKey> keys}) → Map<String, dynamic>
The _apsk value an enrollment publishes: the signing keys that verify what it signs.
apskSigningKeys(Map<String, dynamic> advertisement) → List<ApskSigningKey>
The signing keys an apskAdvertisement advertises, in published order.
authenticatorFor(AtKeysIo io, String atSign, {String? cramSecret, String? enrollmentId, AtChops? chops, SigningAlgoType? signingAlgo, Map<String, dynamic> clientConfig = const {}}) → AtAuthenticator
Builds the authenticator for atSign, reading its credentials from io.
authenticatorForChops(String atSign, AtChops chops, {required SigningAlgoType signingAlgo, required HashingAlgoType hashingAlgo, String? enrollmentId, Map<String, dynamic> clientConfig = const {}}) → AtAuthenticator
Authenticates with a signer the caller already holds, and no keystore.
authenticatorForCramSecret(String atSign, String cramSecret, {Map<String, dynamic> clientConfig = const {}}) → AtAuthenticator
The fourth credential shape: a CRAM secret and nothing else.
authenticatorForPrivateKey(String atSign, String privateKey, {String? enrollmentId, Map<String, dynamic> clientConfig = const {}}) → AtAuthenticator
The legacy credential: a PKAM private key and nothing else.
encodeAtKeysDocument(Iterable<CryptographicMaterial> materials) → List<Map<String, dynamic>>
Encodes one container's materials into its nested keys shape, grouping materials that share a keyId (e.g. the public+private halves of a keypair) and validating that every material in a group agrees on enrollmentId and doesn't repeat a role.
parseAtKeysDocument(List keysJson, {String? enrollmentId, String fieldPrefix = 'keys'}) → List<CryptographicMaterial>
Parses one container's keys array into a flat list of CryptographicMaterial, validating each entry's material (no duplicate role within one keyId) and rejecting a keyId that repeats within this container.
publicKeyKid(Uint8List publicKey) → String
A short identifier for a public key: the first 8 bytes, hex-encoded, of the SHA-256 of the key's raw bytes.
publicKeyKidOfBase64(String pub) → String
publicKeyKid for a key held as base64, which is how every advertisement carries one. Decoding here rather than at each call site is what keeps the preimage the material rather than the encoding.
signPkamChallenge(({SigningAlgoType algorithm, String privateKey, String publicKey}) keyPair, String challenge) → String
Signs challenge as a PKAM proof with keyPair, returning the base64 the pkam: verb carries.

Typedefs

ApproverKeyMaterial = ({String encryptionPrivateKey, String selfEncryptionKey})
What an approver brings to an approval, and all of it: the atSign's encryption private key, which unwraps the APKAM symmetric key a legacy enrollee RSA-wrapped to the atSign, and its self-encryption key, one of the two secrets the approval seals for the enrollee under that symmetric key.
EnrollmentBase = AtEnrollmentRecord
Backward compatibility for AtEnrollmentRecord
RetrofitSerializer = Future<T> Function<T>(AtKeysIo keysIo, String atSign, Future<T> action())
Runs action serialised against anything else retrofitting the same keyfile, for whatever notion of "same keyfile" keysIo implies.