feat: Noports CLI implementation #2304

srieteja · 2025-11-13T10:59:05Z

Closes #1976

- What I did

Introduced Noports CLI with activate and issue-keys commands
Implemented a facade pattern for both commands and added individual fromArgs factories to make instantiation easier.
issue-keys generates copy-pasteable activation strings, activate accepts them.
Created a CLILoggingHandler to display cleaner logs for CLIs

- How I did it

Core Architecture:

Created Activate class with CRAM and APKAM enrollment support
Created IssueKeys class to generate enrollment strings and auto-approve requests
Implemented NoPortsCommand enum for type-safe command routing in noports.dart

Activate Command:

Added noports activate supporting formats: :cram: and :enroll:[:name:]
Created ActivateParams class with parsing logic and validation
Implemented regex-based parsing for activation strings
Implemented help flag handling with HelpRequestedException throw-catch
Added --keyfile option for custom atKeys file paths
Prompts the user for a file path if a keys file already exists at the default or provided atKeys path.

Issue-Keys Command:

Generates an enroll OTP and constructs an activation_string using it.
Waits for the enrollment with the specific app and device name to be created; approves it once created.
Introduced IssueKeysParams that has it's arg parser impl and parsing
Uses default values for namespace and appName
Accepts user input for deviceName (fallback: noports_), keyfile and passphrase
Support for resuming command: Checks for existing pending enrollments with given appName and deviceName, If present it approves it an exits (so re-running the command would simply resume the flow)
Maintains 1-hour OTP expiry with loop termination on expiration

- How to verify it

Run ./buildBinaries in sshnoports/ to generate binaries
Run noports issue-keys <@atsign> to generate an enrollment string
Copy the generated string and run noports activate <string> to activate
Verify enrollment is auto-approved with correct parameters, and the keys file is generated at the user-inputted/default atKeys location

- Description for the changelog

feat: introduce noports CLI with support for commands: 'activate' and 'issue-keys'

…ctivate

packages/dart/sshnoports/bin/noports.dart

srieteja · 2025-11-17T22:02:28Z

packages/dart/sshnoports/lib/src/noports_cli/issue_keys/np_issue_keys.dart

+    StringBuffer cbuf = StringBuffer();
+    cbuf.append(NPIssueKeys.baseEnrollCommand
+        .replaceFirst('<atsign>', params.atsign)
+        .replaceFirst('<otp>', params.otp!));


baseEnrollCommand is <atsign>:enroll:otp:<otp>; replace placeholders with actual values

srieteja · 2025-11-17T22:04:52Z

packages/dart/sshnoports/lib/src/noports_cli/issue_keys/np_issue_keys.dart

+          .fetchEnrollmentRequests(enrollmentListParams: enrollListParams);
+
+      if (enrollRequests.isEmpty) {
+        // keeps the loop active until enrollment fetched or terminated


Currently keeps retrying forever until successful or terminated. Should we consider having a retry limit?

Nope; but we should consider having a resume if the user accidentally terminated before successful

The resume mechanism has been added through the latest commits. The mechanism works by serializing the NPActivateParams and then reading when available.

packages/dart/sshnoports/lib/src/create_at_client_cli.dart

packages/dart/sshnoports/buildBinaries

packages/dart/sshnoports/pubspec.lock

…e/src/commands/

…ctivate

srieteja · 2025-12-16T22:42:48Z

Changes in the last batch of commits:

Moved the code to noports_core/src/commands/
Created new exception HelpRequestedException that is thrown when help is requested, help messages displayed when caught.
Created a separate arg parser + params class for IssueKeys: IssueKeysParams
Modified the existing activate params class to a hybrid one: Regex based reading of params from activation_string, then an arg parser for the rest.
Removed the state file based resume mechanism; replaced with a check for matching pending enrollments before the usual flow.
Updated help messages to be more descriptive and included examples

srieteja · 2025-12-16T22:46:38Z

packages/dart/noports_core/lib/src/commands/activate/activate_impl.dart

+    final String? keysFilePath;
+
+    if (_params.atKeysFilePath == null) {
+      // Use the default path from onboarding service preferences


Workaround to avoid conflicts with creating atKeys files. Currently fetches the defaultPath from OnboardingServiceImpl.

Changes required: OnboardingService should throw a dedicated exception for key file name collisions, which can then be caught and handled.

Need to address this issue fully in this PR. Find the places that MUST have file existence checking (onboard, enroll), ensure the checking always happens there. Remove file existence checking from elsewhere and verify that all the ways we create atKeys files do end up having a file existence check so we don't ever overwrite keys files. As a final safeguard, put a check into the place we finally write an AtKeys file and do not permit overwriting.

srieteja · 2025-12-16T22:50:30Z

packages/dart/noports_core/lib/src/commands/issue_keys/issue_keys_impl.dart

+  /// Returns: 0 on success, 1 on failure
+  Future<int> wrappedMain() async {
+    await _initAtClient();
+


If existing matching enrolment present, approves it

XavierChanth

Minor changes and some questions.

XavierChanth · 2025-12-16T22:48:39Z

packages/dart/noports_core/lib/src/commands/activate/activate_params.dart

+      );
+    }
+
+    final activationString = results.rest.first;


Why .first instead of .single?

.first keeps the cli lenient by avoiding errors when extra values are passed. But .single seems clearer and more straighforward, so I've replaced .first with .single through 90a00f6

packages/dart/noports_core/lib/src/commands/activate/activate_params.dart

XavierChanth · 2025-12-16T22:53:33Z

packages/dart/noports_core/lib/src/commands/activate/activate_impl.dart

+  final logger = AtSignLogger('Activate', loggingHandler: CLILoggingHandler())
+    ..level = 'info';
+
+  Activate._(this._onboardingService, this._params);


Nit: the strongly constructor shouldn't be private, most non-binary consumers of this api will prefer this over the factory constructor.

Constructor made public through 90a00f6

XavierChanth · 2025-12-16T22:55:03Z

packages/dart/noports_core/lib/src/commands/issue_keys/issue_keys_impl.dart

+    loggingHandler: CLILoggingHandler(),
+  )..level = 'info';
+
+  IssueKeys._(this._params);


Constructor made public through 90a00f6

XavierChanth · 2025-12-16T22:58:55Z

packages/dart/noports_core/lib/src/commands/utils/regex.dart

+
+  // Enrollment: <atsign>:enroll:otp:<otp>[:name:<device>:keyfile:<path>]
+  static final enroll = RegExp(
+    r'^(?<atsign>[^:]+):enroll:otp:(?<otp>[A-Za-z0-9]{6})'


This is ordered, which is fine simple is best. Just make sure the Desktop app respects the same order when it gets implemented there.

Ideally the app consumes the same classes.

This was left behind. The keys file is not accepted through the activation_string anymore; it can be passed as a separate arg with -k (or) -key-file. I'll make sure the desktop app works as expected.

XavierChanth · 2025-12-16T22:59:43Z

packages/dart/noports_core/lib/src/commands/utils/usage_messages.dart

+${chalk.bold('Usage:')} noports activate ${chalk.cyan('<activation_string>')} [options]
+
+${chalk.bold('Options:')}
+  -k, --keyfile <path>        Path to save atKeys file


Looks like the help wasn't updated

I did update it earlier, I also reworked them again through (8a4a9d7).

XavierChanth · 2025-12-16T23:01:04Z

packages/dart/noports_core/lib/src/common/cli_logging_handler.dart

+        return chalk.red('ERR');
+      case Level.INFO:
+      default:
+        return chalk.blueBright('INFO');


Why not upstream this to atlogger hidden behind a boolean switch?

XavierChanth · 2025-12-16T23:01:30Z

packages/dart/noports_core/lib/src/common/help_requested_exception.dart

@@ -0,0 +1,3 @@
+class HelpRequestedException implements Exception{


Your Pr needs formatting

addressed in my last commit

JeremyTubongbanua · 2025-12-17T15:51:47Z

Feedback:

--version or show version in usage instructions

So there's 3 functions to the NoPorts CLI that I'm aware of

noports activate (CRAM Onboarding)
noports issue-keys (OTP and Auto Approve)
noports enroll (we want this to be a new command, separate from activate)

Right now 1 and 3 are in the same activate command, but I think it should be separate commands

…ctivate

XavierChanth · 2025-12-17T23:26:57Z

Right now 1 and 3 are in the same activate command, but I think it should be separate commands

Then it no longer solves the original goal.

The original goal is to create a string format that encodes all of the information required to transmit an atSign between machines for use with NoPorts. As soon as you separate the commands, or add options and flags, you have now coupled the use-case to the CLI and it is no longer compatible with the desktop app.

JeremyTubongbanua · 2025-12-17T23:32:17Z

Right now 1 and 3 are in the same activate command, but I think it should be separate commands

Then it no longer solves the original goal.

The original goal is to create a string format that encodes all of the information required to transmit an atSign between machines for use with NoPorts. As soon as you separate the commands, or add options and flags, you have now coupled the use-case to the CLI and it is no longer compatible with the desktop app.

Makes sense,

It was just some feedback I had during my 30min call with Srie. If there was an original vision that I wasn't aware of, then we can ignore my suggestion

XavierChanth · 2025-12-17T23:35:12Z

Right now 1 and 3 are in the same activate command, but I think it should be separate commands

Then it no longer solves the original goal.
The original goal is to create a string format that encodes all of the information required to transmit an atSign between machines for use with NoPorts. As soon as you separate the commands, or add options and flags, you have now coupled the use-case to the CLI and it is no longer compatible with the desktop app.

Makes sense,

It was just some feedback I had during my 30min call with Srie. If there was an original vision that I wasn't aware of, then we can ignore my suggestion

This is covered in my onboarding document.

…ctivate

gkc · 2025-12-23T11:44:56Z

packages/dart/noports_core/lib/src/commands/activate/activate_impl.dart

+    }
+
+    logger.shout('KeysFile exists at $keysFilePath');
+    _params.atKeysFilePath = promptUser(


what happens if the user puts the same path in again?

gkc · 2025-12-23T11:50:18Z

packages/dart/noports_core/lib/src/commands/activate/activate_impl.dart

+    final String? keysFilePath;
+
+    if (_params.atKeysFilePath == null) {
+      // Use the default path from onboarding service preferences


Need to address this issue fully in this PR. Find the places that MUST have file existence checking (onboard, enroll), ensure the checking always happens there. Remove file existence checking from elsewhere and verify that all the ways we create atKeys files do end up having a file existence check so we don't ever overwrite keys files. As a final safeguard, put a check into the place we finally write an AtKeys file and do not permit overwriting.

gkc · 2025-12-23T11:52:03Z

packages/dart/noports_core/lib/src/commands/activate/activate_params.dart

+      );
+  }
+
+  static String? _parseAtsign(String input, ActivateType type) {


Return type should be Atsign? not String?

gkc · 2025-12-23T11:52:48Z

packages/dart/noports_core/lib/src/commands/activate/activate_params.dart

+    return match?.namedGroup(ActivateRegexGroups.deviceName);
+  }
+
+  Map<String, String?> toJson() {


Why is type not part of the json?

You are missing a test somewhere to ensure this kind of problem doesn't happen

after further discussion we concluded that toJson is no longer needed and can be removed from this class

gkc · 2025-12-23T11:54:54Z

packages/dart/noports_core/lib/src/commands/issue_keys/issue_keys_impl.dart

+    if (existingEnrollment != null) {
+      await _approveEnrollment(existingEnrollment);
+      return 0;
+    }


personal preference, I would prefer the rest of this code were in an else block

gkc · 2025-12-23T11:57:47Z

packages/dart/noports_core/lib/src/commands/issue_keys/issue_keys_impl.dart

+
+    if (results.isNotEmpty) {
+      logger.info('Enrollment found with id: ${results.first.enrollmentId}');
+      return results.first;


Should we be asserting there be just one? Or at least an explanation that we can only expect at most one result.

gkc · 2025-12-23T12:11:00Z

packages/dart/noports_core/lib/src/common/cli_logging_handler.dart

+        return chalk.red('ERR');
+      case Level.INFO:
+      default:
+        return chalk.blueBright('INFO');


gkc · 2025-12-23T12:13:29Z

packages/dart/sshnoports/bin/noports.dart

+  displayBanner();
+  AtSignLogger.root_level = 'severe';
+  return AtSignLogger('NoPorts', loggingHandler: CLILoggingHandler())
+    ..level = 'info';


No way for the user to change the log level?

add --verbose | -v and --debug as we have for sshnpd

srieteja and others added 12 commits November 6, 2025 17:59

feat: introduce np_activate_params class and np_activate_utils

4b1083f

feat: introduce np_activate_impl containing actual cram/enroll wrappers

99a0d12

feat: introduce np_activate_cli

e84fd0c

build: update buildBinaries to compile noports_cli

7990ba9

feat: reintroduce NPActivate impl

6d726f2

feat: introduce NPIssueKeys impl

2b5b727

feat: introduce noports_cli utils/

75f4a85

feat: introduce CLI entrypoint 'noports' in sshnoports/bin

060c86f

chore: temp pubspec overrides for at_client and onboarding_cli

f45b60e

Merge branch 'trunk' into noports_activate

5b4a778

docs: added method docs

4a0d2c7

Merge remote-tracking branch 'origin/noports_activate' into noports_a…

3d56f0e

…ctivate

This was referenced Nov 13, 2025

fix: expose atKeys as method parameter in OnboardingService interface + ready for publish at_onboarding_cli v1.14.2 atsign-foundation/at_client_sdk#1710

Merged

NoPorts onboarding UX #2252

Open

srieteja and others added 8 commits November 13, 2025 20:33

build(deps): add at_auth dep in sshnoports

7a01f69

Merge branch 'trunk' into noports_activate

d4638d9

refactor: readability improvements + bug fixes + docs

0bbf4ce

build: consume at_onboarding_cli v1.14.1

a36b39e

Merge remote-tracking branch 'origin/noports_activate' into noports_a…

6c88288

…ctivate

Merge branch 'trunk' into noports_activate

68b0a94

fix: do not pass atkeys path to atClient

f4c2cac

Merge remote-tracking branch 'origin/noports_activate' into noports_a…

f250cda

…ctivate

srieteja commented Nov 17, 2025

View reviewed changes

packages/dart/sshnoports/bin/noports.dart Outdated Show resolved Hide resolved

srieteja commented Nov 17, 2025

View reviewed changes

packages/dart/sshnoports/lib/src/create_at_client_cli.dart Show resolved Hide resolved

srieteja commented Nov 17, 2025

View reviewed changes

packages/dart/sshnoports/buildBinaries Show resolved Hide resolved

srieteja commented Nov 17, 2025

View reviewed changes

packages/dart/sshnoports/pubspec.lock Outdated Show resolved Hide resolved

srieteja requested review from XavierChanth and removed request for XavierChanth November 17, 2025 22:18

gkc marked this pull request as draft December 16, 2025 11:04

srieteja added 6 commits December 16, 2025 22:24

feat: Introduce separate parser for issue-keys and consume it

f7527bc

feat: activate command uses a hybrid parser. relocated to noports_cor…

64ea4a6

…e/src/commands/

feat: move utils to noports_core/src/commands/util/

eabd000

Merge branch 'trunk' into noports_activate

8ba58bc

feat: introduce HelpRequestedException use it

492755c

Merge remote-tracking branch 'origin/noports_activate' into noports_a…

12cedd7

…ctivate

srieteja commented Dec 16, 2025

View reviewed changes

fix: changes from self review

3a7ddbd

XavierChanth requested changes Dec 16, 2025

View reviewed changes

srieteja added 4 commits December 18, 2025 02:48

fix: constructors made public + minor formatting

90a00f6

Merge branch 'trunk' into noports_activate

402c948

docs: updated usage messages + minor fixes

8a4a9d7

Merge remote-tracking branch 'origin/noports_activate' into noports_a…

c59f870

…ctivate

srieteja marked this pull request as ready for review December 17, 2025 23:16

srieteja requested review from XavierChanth and gkc December 17, 2025 23:16

srieteja requested a review from JeremyTubongbanua December 18, 2025 16:32

srieteja and others added 5 commits December 18, 2025 22:02

Merge branch 'trunk' into noports_activate

a882ef9

Merge branch 'trunk' into noports_activate

56faa5d

chore: minor tweaks and cleanup

edd41b2

Merge remote-tracking branch 'origin/noports_activate' into noports_a…

5070f49

…ctivate

Merge branch 'trunk' into noports_activate

0a3b19e

gkc requested changes Dec 23, 2025

View reviewed changes

		@@ -0,0 +1,3 @@
		class HelpRequestedException implements Exception{

feat: Noports CLI implementation #2304

Are you sure you want to change the base?

feat: Noports CLI implementation #2304

Uh oh!

Conversation

srieteja commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Core Architecture:

Activate Command:

Issue-Keys Command:

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

srieteja commented Dec 16, 2025

Uh oh!

srieteja Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

XavierChanth left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JeremyTubongbanua commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

XavierChanth commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JeremyTubongbanua commented Dec 17, 2025

Uh oh!

XavierChanth commented Dec 17, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

srieteja commented Nov 13, 2025 •

edited

Loading

srieteja Dec 16, 2025 •

edited

Loading

JeremyTubongbanua commented Dec 17, 2025 •

edited

Loading

XavierChanth commented Dec 17, 2025 •

edited

Loading