The Atsign FoundationThe Atsign Foundation

pub package pub points gitHub license

at_client_cli

The Atsign Protocol for a Dart command-line program, daemon or server:

  • at_activate and at_register, for registering, activating and enrolling atSigns from a terminal;
  • CLIBase, which turns a program's standard command-line flags into an online AtClient;
  • CliKeys, where those programs keep an atSign's keyfile and local store.

The lifecycle itself is at_client's — Atsign.activate, Atsign.open and Atsign.enroll do the work, and this package gives them a command line. It replaces at_onboarding_cli and at_cli_commons: see Moving from at_onboarding_cli and at_cli_commons.

If you're new to the Atsign Protocol lifecycle (register → activate → APKAM enroll), read at_auth's README first — this package is the CLI concretisation of that model. at_client_flutter is the Flutter-UI equivalent.

Turnkey CLI tools

Both ship as executables when this package is globally activated:

dart pub global activate at_client_cli

at_register — get a free atSign

at_register -e your_email@example.com

Fetches a free atSign, emails you a verification code, then activates the atSign once you paste the code back. The generated .atKeys file lands in ~/.atsign/keys/.

The registrar API key names your app to the registrar. at_register sends the one in AT_REGISTRAR_API_KEY when it is set, and otherwise a key built into at_client_cli; to name your own app, create a key via the registrar at my.atsign.com and set the variable to it.

at_register takes no --posture: it activates at at_client's default (legacy today). An app that runs at pqReady or pqActive upgrades those keys itself at its first start, which needs the atServer; until that start completes, a pqActive client writes nothing. An atSign you already hold can be activated at a posture of its own with at_activate onboard --posture.

at_activate — the atSign's lifecycle from the terminal

Every invocation should name a command. With none, at_activate still runs onboard, as at_onboarding_cli 1.x did, but prints a deprecation warning, because a later major will refuse it.

# Activate a newly registered atSign with the CRAM secret the registrar sent
at_activate onboard -a @alice -c <cram_secret>

# ...or let at_activate fetch it: the registrar emails a verification code,
# which you paste back. It sends AT_REGISTRAR_API_KEY when it is set, and
# otherwise the built-in key, as at_register does
at_activate onboard -a @alice

Either form writes the master .atKeys to ~/.atsign/keys/@alice_key.atKeys. These are the root of trust for @alice — back them up.

The remaining commands run on the keyfile -k names (that one by default):

Command What it does
status -a @alice asks where the atSign stands; the exit code says: 0 activated, 1 atServer up but not yet activated, 2 atServer unreachable, 3 no such atSign, 4 atDirectory unreachable
enroll -a @alice --app <app> --device <device> --namespaces <ns:rw,...> --passcode <otp> submits an APKAM enrollment for a new app and device and waits for its approval; run again for the same app and device, it resumes the wait rather than submitting a second request
otp / spp issues a one-time passcode, or sets a semi-permanent one, that a new enrollment quotes
list, fetch the enrollment roster, or one enrollment's record
approve, deny, revoke, unrevoke, delete decides an enrollment by its id; auto listens and approves the requests that match its app and device patterns
interactive a shell over the commands above
decrypt writes a passphrase-protected keyfile out decrypted

--posture legacy|pqReady|pqActive is accepted on every command and decides what a client built for it does post-quantum (see the at_client README). An unnamed --posture is at_client's default on every command (legacy today), and onboard and enroll say so when they take it. Approving a post-quantum enrollment needs the post-quantum providers, so under legacy at_client refuses such an approval when it reads the request; pass --posture pqReady to approve one. enroll --key-exchange legacy|pq chooses how the enrollment's symmetric key travels, for the approver that will pick the request up; pq needs --posture pqReady or pqActive, since an rsa2048 enrollment with the pq key exchange is refused.

On an atSign that has published any namespace key, enroll a device with --posture pqReady or above, so its approval conveys the namespace keys. A device enrolled at the legacy key exchange whose app runs at pqReady or above re-enrolls itself at its first start and asks the atSign's other enrollments for those keys, which only an enrollment online at the time can answer; one whose app runs legacy reads none of the atSign's post-quantum data. approve warns when it approves such a request, and approves it as asked.

APKAM enrollment

A new device / app authenticating as an existing atSign should go through APKAM rather than asking the user for their master keys. The worked example lives under example/bin/apkam_examples/:

  • apkam_enroll.dart — the new device submits an enrollment request scoped to specific namespaces
  • enroll_app_listen.dart — a device holding the master keys listens for and approves / denies incoming requests, through client.enrollments
  • apkam_authenticate.dart — the new device authenticates with its newly-issued scoped keys

Full step-by-step walkthrough: example/README.md.

Library usage

A program's client: CLIBase

CLIBase turns the standard command-line flags into an online client:

import 'package:at_client_cli/at_client_cli.dart';

Future<void> main(List<String> args) async {
  final parser = CLIBase.createArgsParser(namespace: 'my_app');
  final AtClient client = (await CLIBase.fromCommandLineArgs(args,
          parser: parser,
          preference: AtClientPreference(posture: PqPosture.pqActive)))
      .atClient;
  // ...
  await client.stop();
}

-a names the atSign, -k its keyfile (~/.atsign/keys/<atSign>_key.atKeys by default), -r the atDirectory, -s the local store and -P the keyfile's pass-phrase; --help lists the rest. fromCommandLineArgs waits up to --max-connect-attempts tries, 3 seconds apart, for the client to come online. Otherwise it stops the client and throws:

  • AtCredentialRefusedException when the atServer refuses the keys, naming the cause, and saying when the enrollment awaits approval or was denied;
  • AtEnrollmentException when the enrollment request the keyfile holds is denied or expires;
  • SecondaryNotFoundException when the atDirectory has no atServer for the atSign;
  • SecondaryServerConnectivityException when the atServer is not reached in time, the one a retry loop should catch.

A keyfile still holding only its enrollment request is resumed: the program says it is waiting for approval of that enrollment, waits as at_activate does, and runs once it is approved. Ctrl-C while it waits keeps the request for the next run.

Pass preference: an AtClientPreference to set anything the flags do not.

The lifecycle verbs, with CliKeys

A program that does not take CLIBase's flags calls at_client's verbs itself. The one import carries them, since at_client_cli re-exports at_client's native API, its storage backends and mixins, the registrar and the logging handlers. CliKeys gives the verbs the keyfile and store a command-line program keeps. Unless it sets AtSignLogger.root_level, such a program logs only the SDK's warnings, to stdout; AtSignLogger.defaultLoggingHandler = StdErrLoggingHandler() sends them to stderr:

import 'package:at_client_cli/at_client_cli.dart';

final preference = AtClientPreference(posture: PqPosture.pqActive)..namespace = 'my_app';
final keys = CliKeys.fileFor('@alice');       // ~/.atsign/keys/@alice_key.atKeys
final storage = CliKeys.storageFor('@alice', program: 'my_app');
final lookUps = lookUpsFor(preference.rootDomain);
final atDirectory =
    CacheableSecondaryAddressFinder(preference.rootDomain, preference.rootPort);

CliKeys.fileFor takes a path and a passPhrase; CliKeys.storageFor puts the store at ~/.atsign/storage/<atSign>/<program>/<id>, single when no id is given, where CLIBase keeps it for that namespace, or at path, and the client closes it when it stops. lookUps builds every connection the client opens, and lookUpsFor(rootDomain) is the one CLIBase uses: proxyLookUps() when the root domain names a proxy (proxy:host:port), which sends from:<atSign> first on every connection so the proxy can route it, and secureSocketLookUps(), TLS on TCP, otherwise.

at_activate's onboard and enroll share one local store per atSign, under ~/.atsign/storage/<atSign>/at_activate/, so running two of them at once for the same atSign is not supported: the second fails when it opens the store.

Activate a new atSign with its CRAM secret (or run at_activate onboard without -c, which fetches one from the registrar against an emailed verification code):

final owner = await Atsign('@alice').activate(
    cramSecret: secret, keys: keys, preference: preference, storage: storage,
    lookUps: lookUps, secondaryAddressFinder: atDirectory);

Open a client on keys already held. It comes back online, offline or refused, and connection says which:

final client = await Atsign('@alice').open(
    keys: keys, preference: preference, storage: storage,
    lookUps: lookUps, secondaryAddressFinder: atDirectory);
print(client.connection.current);

Enrol a new device, quoting a passcode an enrolled client issued, and wait for that client to approve. The keyfile is the resume record: a request already in it is picked up by resumeEnrollment rather than repeated.

final deviceKeys = CliKeys.fileFor('@alice', path: 'my_app_laptop.atKeys');
final pending = await Atsign('@alice').enroll(
    otp: otp, app: 'my_app', device: 'laptop',
    namespaces: {'my_app': 'rw'}, keys: deviceKeys, preference: preference,
    lookUps: lookUps, secondaryAddressFinder: atDirectory);
final enrolled = await pending.client(preference,
    storage: CliKeys.storageFor('@alice',
        program: 'my_app', id: pending.enrollmentId));

The approving side, on an enrolled client:

for (final request in await owner.enrollments.pending()) {
  await owner.enrollments.approve(request.enrollmentId!);
}
final passcode = await owner.enrollments.otp();

Worked examples covering each flow are in example/bin/.

Moving from at_onboarding_cli and at_cli_commons

Upgrading to at_client 4.0 takes a program through the whole move, at_client included; this section covers this package's own changes.

at_client_cli carries both packages' code. Their last majors, at_onboarding_cli 2.0.0 and at_cli_commons 4.0.0, re-export it under a deprecated library and keep the at_activate and at_register executables, so dart pub global activate at_onboarding_cli still installs working tools. A program that used AtOnboardingService, AtOnboardingPreference or the helpers below changes code at the bump; one that used only CLIBase and the path helpers changes its dependency and import. The .atKeys file at_onboarding_cli 1.x wrote is read unchanged.

at_onboarding_cli 1.x, at_cli_commons 3.x at_client_cli 1.0
package:at_onboarding_cli/at_onboarding_cli.dart, package:at_cli_commons/at_cli_commons.dart package:at_client_cli/at_client_cli.dart
dart pub global activate at_onboarding_cli dart pub global activate at_client_cli; the old command still installs the same tools
CLIBase(..., preference: AtOnboardingPreference()) unchanged, except that preference: takes an AtClientPreference
CLIBase on a refused first open, AtOpenRefusedException AtCredentialRefusedException for every refusal; SecondaryNotFoundException for an atSign the atDirectory does not know; SecondaryServerConnectivityException only for an outage
AtOnboardingServiceImpl(atSign, pref).authenticate(), then .atClient CLIBase.fromCommandLineArgs(...), or Atsign(atSign).open(...) with CliKeys
.onboard() Atsign(atSign).activate(...), or at_activate onboard
.enroll(...), .sendEnrollRequest(...), .awaitApproval(...), .createAtKeysFile(...) Atsign(atSign).enroll(...) and PendingEnrollment.client(...); Atsign.resumeEnrollment picks a pending request up after a restart
.isOnboarded() at_activate status, or at_lookup's checkAtSignServer
.close() atClient.stop()
.atLookUp, .atChops, .atAuth, .completeActivation(), .getAtClient() none; the client's own connection does what they exposed
AtOnboardingPreference AtClientPreference; its atKeysFilePath and passPhrase are CliKeys.fileFor(atSign, path: ..., passPhrase: ...), its storagePath is CliKeys.storageFor(...). With no path, storageFor opens a new store at ~/.atsign/storage/<atSign>/<program>/single, not the old ~/.atsign/at_onboarding_cli/storage/<atSign>/hive; pass that directory as path to keep using the old store
AtOnboardingPreference()..signingAlgoType = ... AtClientPreference(posture: ..., authenticationKeyAlgorithm: ...), fixed at construction
createAtClient(...) createAtClient(...), unchanged: the same parameters, and the client at_activate's commands open
OnboardingUtil at_activate onboard fetches a CRAM secret, and at_register a free atSign, each with the registrar API key in AT_REGISTRAR_API_KEY when it is set, or a built-in one
AuthKeyType none: read a keyfile with CliKeys.fileFor(atSign).read(atSign)
MySyncProgressListener a SyncProgressListener of the program's own
package:at_onboarding_cli/src/activate_cli/activate_cli.dart AtActivate.main(args), or the at_activate executable
AtOnboardingException and its subclasses AtClientException, which they extended
at_activate -a @alice -c <secret> (no command) at_activate onboard -a @alice -c <secret>; an invocation naming no command still runs onboard, with a deprecation warning
CLIBase's -d/--legacy-root-domain, and createArgsParser(addLegacyRootDomainArg: ...) -r/--root-server; the option and the parameter are gone, and at_activate's -d is still the device name
--hashingAlgoType gone; it did nothing
(no signing-algorithm flag) --posture legacy|pqReady|pqActive on every command; enroll --key-exchange legacy|pq for how the enrollment's key travels
the *.enrollment.checkpoint file gone; the keyfile holds the pending keys
at_activate's store under ~/.atsign/at_onboarding_cli/storage/ under ~/.atsign/storage/<atSign>/at_activate/, started afresh; the keys, in the keyfile, are untouched
the keyfile onboard writes at_auth's own document: the self-encryption key is no longer duplicated under the atSign, and a passphrase-protected file uses a salted envelope that 1.x tooling cannot read

Where to go next

  • at_auth — the keyfile format and key stores, and the protocol layer under at_client
  • at_client_flutter — the Flutter-UI equivalent of this package

Open source usage and contributions

BSD3-licensed. See CONTRIBUTING.md for guidance on setting up tools, running tests, and raising a PR.

Libraries

at_client_cli
The Atsign Protocol for a Dart command-line program, daemon or server: CLIBase, which turns the standard flags into an open client, createAtClient, which opens a command's client from a keyfile, CliKeys, and the at_activate and at_register tools as AtActivate and AtRegister. It re-exports at_client's native API, its storage backends and mixins, the registrar and the logging handlers, so a program needs no other SDK import.