Design & Objectives — Passbolt.Api + Passbolt.Cli charter

[davidnmbond]

This issue is the project charter: the design, objectives, and definition of done for Passbolt.Api and its companion Passbolt.Cli.

Background

Passbolt integration in our tooling currently goes through go-passbolt-cli, which is a thin wrapper over the go-passbolt Go library. It does not surface per-resource permissions/owners, which blocks ownership auditing (see PanoramicData.Skills#540 and OPS-63894 — "every entry needs ≥2 owners / a group owner"). Rather than depend on a Go binary and wait on upstream, we own a first-class .NET client in the house style (LogicMonitor.Api, ServiceNow.Api, Jira.Api) with a companion CLI (LogicMonitor.Cli, Meraki.Cli, Rundeck.Cli).

Design

• Passbolt.Api — typed .NET client:
  • Refit-backed REST interfaces, System.Text.Json, DI-friendly PassboltClient + PassboltClientOptions, async throughout.
  • GPGAuth challenge-response login (verify → login → decrypt server token → login → session cookie + X-CSRF-Token), with MFA/TOTP support.
  • OpenPGP via a maintained .NET library (BouncyCastle / PgpCore) for the auth-token decrypt and for secret encrypt/decrypt.
  • Clean separation: Apis/ (Refit interfaces), Data/ (models), Requests/ (request bodies).
• Passbolt.Cli — thin verb wrapper over Passbolt.Api (list/get/create/update/share resources, folders, users, groups; permissions/ownership reporting; status). Packaged/distributable like the other *.Cli tools so skills can shell into it.

Objectives

1. Meet all of Oscar's requirements (NuGet governance)

Comply fully with the PanoramicData.NugetManagement standard (its NEW_NUGETS.md rule set) and pass its governance scanner as compliant. That includes: NBGV (version.json) versioning; Central Package Management (no inline versions); TreatWarningsAsErrors + nullable + generated XML docs; complete package metadata + symbols (snupkg); README/LICENSE/CONTRIBUTING/SECURITY; CI + CodeQL + Dependabot; xUnit v3 tests using AwesomeAssertions with failSkips: true on unit test projects; clean tag-triggered publish. (Repo is already scaffolded to this bar — keep it green.)

2. Full feature parity with the Passbolt REST API

Cover the complete public API surface, not just what today's callers need. Target areas (extend as the API evolves):

• Server status / health
• Me (current user)
• Users
• Groups (+ group user memberships)
• Roles
• Resources
• Folders
• Permissions
• Comments
• Avatars
• Resource types
• Secrets (encrypt/decrypt of secret values, per-recipient)
• Resource/folder share (create/update/delete permissions)
• Favorites
• Tags / metadata
• Password expiry / TOTP resource types
• MFA (TOTP verify) as part of auth
• Move (resources/folders)
• Groups create/update/delete + membership mutation
• Healthcheck detail / settings
  (Checklist is a starting point from the current Apis/ set — verify each against the live API and the Passbolt OpenAPI/CakePHP routes; unchecked = not yet implemented or not yet verified.)

3. Serve the ownership-audit requirement (PanoramicData.Skills#540)

Provide, and prove with tests, the capability that motivated this: enumerate resources with their permissions/owners (GET /resources.json?contain[permission]=1&contain[permissions]=1), resolve principals to user vs group, and support the audit filters:

• resources with no group owner, and/or
• resources with fewer than two owner principals (permission type 15).
  Once shipped, the passbolt skill should shell into Passbolt.Cli for this (replacing the go-passbolt-cli dependency), unblocking OPS-63894.

Definition of done

1. Passbolt.Cli project exists in the solution and is distributable.
2. Feature-parity checklist (objective 2) complete and each item test-covered.
3. Ownership report (objective 3) implemented with unit + integration tests.
4. Oscar's governance scanner reports the repo compliant; CI publishes from a tag.
5. GPGAuth (+MFA) verified against a live Passbolt instance.

Related

• PanoramicData.Skills#540 (ownership report — the motivating requirement)
• Feature: expose per-resource permissions/owners in list/get (or a new command) passbolt/go-passbolt-cli#136 (upstream request that would also expose permissions)
• Trademark and Project Identity Clarification #7 (trademark & project identity — must be resolved before/at first public release)

[davidnmbond]

Passbolt.Cli landed (commit bae65cd) — definition-of-done item 1 (a distributable CLI project) is done, and objective 3 (the ownership audit) is delivered as passbolt audit ownership.

• Installable as a .NET global tool: dotnet tool install -g Passbolt.Cli → passbolt. Verified install → run → uninstall end to end.
• Cobra-style subcommands (Spectre.Console.Cli), human tables + clean --json (stdout is JSON-only), config file + PASSBOLT_* env + per-command options, passphrase never persisted.
• Commands: status, whoami, configure, resource list/get/delete, user list/get, group list/get, folder list/get, permission list, audit ownership (flags < N owners or no group owner).
• Builds clean under TreatWarningsAsErrors; README documents usage + positively references passbolt/go-passbolt(-cli).

Still open for full parity (objective 2) / DoD: create/update/share (need PGP secret encryption), group-membership mutation, resource types, favorites, tags, MFA/TOTP in auth; and CI wiring to publish the CLI tool package on tag. Live GPGAuth (+MFA) verification against a real server still pending (DoD item 5).

[davidnmbond]

Published + CLI parity progress (v1.0.23).

• CI now packs & publishes both Passbolt.Api and the Passbolt.Cli .NET tool on tag (Trusted Publishing). Both are live on NuGet.org; dotnet tool install -g Passbolt.Cli installs the passbolt command.
• CLI write surface added (no-secret ops): user create/update/delete, group create/add-member/delete, folder create/update/delete, resource update (metadata), role list — on top of the existing reads + audit ownership.

Remaining for full parity (objective 2): resource create, secret rotation, and share — all need PGP secret encryption to each recipient's public key. Broken out as #31 (library work first). Group-membership removal also needs a request-model extension (groups_users[].delete). Live GPGAuth/CRUD verification against a real server still pending (DoD item 5).