Protected Registry Desktop Review Notes

Protected Registry Desktop Review Notes

This note summarizes the current review points for the Protected Registry Desktop App after checking the login, package command, and package entitlement flows.

User Expectation

The desktop app should behave like the GitHub or VS Code login flow:

desktop app opens
  -> unauthenticated users see only the login screen
  -> clicking login opens the FractalOps browser login
  -> the browser redirects to a local loopback callback
  -> the desktop app stores the completed session
  -> protected package features become available

The app should not expose low-level OIDC fields to the user:

• issuer URL
• client ID
• callback URL
• redirect URI

Those values are application/build configuration, not user input.

Environment Contract

FractalOps base configuration should be read from the repository root .env or build environment.

Primary value:

FRACTALOPS_BASE_URL

The desktop app should not introduce a duplicate portal URL variable when the existing base URL can define the FractalOps API and portal target.

OIDC-specific values are still app configuration, but they should remain hidden from the UI:

PROTECTED_REGISTRY_OIDC_ISSUER_URL
PROTECTED_REGISTRY_OIDC_CLIENT_ID
PROTECTED_REGISTRY_OIDC_REDIRECT_URI

The loopback redirect path should be stable and app-owned:

http://127.0.0.1:<port>/oidc/callback

The Keycloak client must allow loopback redirects for both 127.0.0.1 and localhost with dynamic ports.

Screen Behavior

Before login:

• show only the login gate
• hide or disable package/build/delivery controls
• do not show raw JSON command output as the main user experience

After login:

• show package, build, delivery, and session surfaces
• show logout in the session area
• keep access tokens and refresh tokens hidden
• show concise status or errors instead of raw command JSON

Tab Meaning

Packages:

• install protected packages
• publish protected packages
• request short-lived npm registry tokens from FractalOps
• use only package/action-scoped tokens

Builds:

• harden package artifacts before delivery
• produce integrity, SBOM, provenance, and protected build manifests
• keep raw source separate from protected output

Delivery:

• create encrypted customer delivery bundles
• submit delivery manifests to FractalOps
• request customer-specific delivery grants
• store key references, not raw keys

Session:

• show authenticated state
• show redacted session details only
• provide logout
• help diagnose session storage without printing secrets

Permission Model

Install and publish are not generic app buttons. They require package-level authorization.

Required decision shape:

subject
  -> project
  -> package
  -> action: install | publish
  -> allow | deny

Important cases:

• a user may be allowed to install but denied publish
• a user may be denied both
• a package may be missing from the project
• a package may be disabled or archived
• a package may exist but have no install or publish policy for the user

The UI must reflect this:

• if install is denied, disable install for that package
• if publish is denied, disable publish for that package
• if no package entitlement exists, do not optimistically allow actions
• if a stale UI submits a denied action, backend token minting must still deny

Backend Enforcement

FractalOps must make the final decision before issuing an npm token.

Expected flow:

desktop action
  -> FractalOps credential broker
  -> package entitlement resolver
  -> RegistryTokenService
  -> short-lived Nexus npm token
  -> Nexus plugin validates package/action claims

Required token claims:

• tenant_id
• project_slug
• package_name
• package_scope
• allowed_actions
• entitlement_snapshot_id
• artifact_policy
• exp

The Nexus plugin must reject package/action mismatches even when the token is otherwise valid.

Grill-Me Decisions

Question: Should the app ever allow package commands without login?

Recommended answer: No. The first screen should be login-only, and privileged commands should fail without a stored authenticated session.

Question: Should users type OIDC or redirect configuration in the desktop app?

Recommended answer: No. These values belong to .env, build config, or deployment config.

Question: Should FractalOps rely only on project-level roles for install and publish?

Recommended answer: No. Project roles can be a fallback input, but the final decision must be package-level.

Question: Should the frontend decide whether install or publish is allowed?

Recommended answer: No. The frontend can display entitlement state, but the backend must enforce before token minting.

Question: Should missing package policy default to allow?

Recommended answer: No. Missing package policy should deny protected registry actions unless an explicit fallback contract is accepted.

Open Implementation Checks

• Confirm the packaged Windows executable uses the current root .env or build-time environment values.
• Confirm login opens the browser and completes through the loopback callback instead of only starting and stopping a Node helper.
• Confirm the app renders user-friendly status messages instead of raw JSON.
• Confirm package entitlement API results drive disabled install/publish options in the UI.
• Confirm backend token minting denies stale or unauthorized package actions.
• Confirm logout clears the secure session and returns the app to the login gate.