Protected Registry Customer Management And Login

Protected Registry Customer Management And Login

This note captures the customer management and non-OIDC customer login layer for Protected Registry.

Current State

Internal FractalOps users use OIDC.

FractalOps employee
  -> OIDC login
  -> package policy
  -> install | publish | build | deliver

Customers do not use FractalOps OIDC.

Customer
  -> customer_slug + package_name + version + grant_token
  -> POST /v1/packages/registry/customer-tokens/npm
  -> install-only short-lived npm token
  -> npm install <package>@<version>

Implemented customer install and activation proof:

protected_registry_customers
protected_registry_customer_contacts
protected_registry_customer_entitlements
protected_registry_customer_activation_codes
protected_registry_customer_sessions
protected_registry_customer_devices
protected_registry_customer_grants
POST/GET/PUT /v1/packages/customers...
POST /v1/packages/registry/customer-activations
GET  /v1/packages/registry/customer-session
POST /v1/packages/registry/customer-tokens/npm
POST /v1/packages/registry/customer-logout
protected-registry customer-activate
protected-registry customer-session
protected-registry customer-logout
protected-registry customer-install <package>
Desktop customer install form
Desktop customer activation form
Nexus package/version claim enforcement

Grant token install remains as a backward-compatible bridge. The preferred customer flow is activation code plus device/session, then package/version entitlement checks for each short-lived npm token.

Required Target

Company staff must be able to register customers and configure package entitlements for them.

Customers need a login or activation flow that does not require FractalOps OIDC.

Recommended target:

Company staff
  -> FractalOps OIDC
  -> create customer
  -> add customer contact/user
  -> configure package/version entitlements
  -> issue activation code

Customer
  -> Protected Registry Desktop
  -> enter activation code once
  -> device/session registered
  -> install entitled package versions

Staff Management Model

Staff authentication remains FractalOps OIDC.

Staff authorization should use a dedicated customer administration action, not only broad project ownership.

Minimum roles:

customer_admin
customer_support
package_delivery_operator

Recommended permission split:

customer_admin             -> create/update customers, contacts, entitlements, activations
customer_support           -> view customer state, reissue activation, revoke sessions
package_delivery_operator  -> create delivery bundles/grants for package versions

Customer Records

Required tables:

protected_registry_customers
protected_registry_customer_contacts
protected_registry_customer_entitlements
protected_registry_customer_activation_codes
protected_registry_customer_sessions
protected_registry_customer_devices

Existing table:

protected_registry_customer_grants

Use protected_registry_customer_grants as the current install-only bridge. Longer term, split long-lived entitlement from one-time activation/session.

Customer Entitlement Shape

Customer entitlement is version-level, not just package-level.

tenant_id
customer_slug
project_slug
package_name
package_scope
allowed_versions[]
allowed_dist_tags[]
status
starts_at
expires_at
max_downloads
metadata_json
created_by
updated_by

Rules:

customer can install only allowed package versions
customer cannot publish
customer cannot build
customer cannot create delivery bundles/grants
disabled customer denies all customer sessions and token minting
expired entitlement denies new npm tokens

Activation Login

Recommended customer login is activation code plus device/session.

First run:

1. Customer opens Protected Registry Desktop.
2. Customer enters activation code.
3. Desktop computes device_id.
4. POST /v1/packages/registry/customer-activations
5. Server validates activation code and entitlement.
6. Server registers device/session.
7. Server returns customer_session_token.
8. Desktop stores customer_session_token in secure store.

Subsequent install:

1. Desktop loads customer_session_token.
2. Customer selects package/version.
3. POST /v1/packages/registry/customer-tokens/npm
4. Server checks customer session and package/version entitlement.
5. Server returns short-lived npm token.
6. Desktop writes temp .npmrc and runs package manager.
7. Desktop deletes temp .npmrc.

API Plan

Staff APIs:

POST /v1/packages/customers
GET  /v1/packages/customers
GET  /v1/packages/customers/{customer_slug}
PUT  /v1/packages/customers/{customer_slug}

POST /v1/packages/customers/{customer_slug}/contacts
PUT  /v1/packages/customers/{customer_slug}/entitlements
POST /v1/packages/customers/{customer_slug}/activation-codes
POST /v1/packages/customers/{customer_slug}/revoke

Customer APIs:

POST /v1/packages/registry/customer-activations
GET  /v1/packages/registry/customer-session
POST /v1/packages/registry/customer-tokens/npm
POST /v1/packages/registry/customer-logout

Existing customer token route should evolve:

current:
  customer_slug + package_name + version + grant_token

target:
  customer_session_token + package_name + version

Desktop Plan

First screen should support two modes:

FractalOps staff login
Customer activation

Staff mode:

Login with FractalOps
Packages
Builds
Delivery
Session
Customer admin

Customer mode:

Activate
Installed packages
Install entitled package
Repair install
Session

After customer install, Desktop must show usage guidance:

installed package/version
reinstall command
project .npmrc routing
do not commit auth tokens
run Desktop again to refresh short-lived npm token

Project .npmrc Policy

Persist registry routing in the customer project.

@yamon:registry=https://r.yamon.io/
always-auth=true
replace-registry-host=always

Do not persist npm auth tokens in the project.

//r.yamon.io/:_authToken=<token>

That token belongs only in a temp .npmrc or secure user-level flow.

Package Install Behavior

Customer install should run a package manager command:

npm install @yamon/example@1.4.2 --userconfig <temp .npmrc>
pnpm add @yamon/example@1.4.2 --config.userconfig=<temp .npmrc>
yarn add @yamon/example@1.4.2

Default package manager behavior updates package.json.

Expected:

{
  "dependencies": {
    "@yamon/example": "^1.4.2"
  }
}

If the customer deletes node_modules, project .npmrc keeps scoped packages pointed at the protected registry. A fresh customer session/token is still needed for install.

Security Boundaries

Do:

hash activation codes and grant tokens at rest
use short-lived npm tokens
bind customer sessions to customer_slug and device_id
record audit/evidence for activation and token minting
enforce package_name and package_version in JWT and Nexus
support session revoke

Do not:

store raw grant_token
commit npm auth token to project .npmrc
let customer tokens publish/build/deliver
use URL hiding as security
let package-level entitlement imply all versions

Grill Decisions

Question 1: Should customers use FractalOps OIDC?

Recommended answer: No. Use activation code plus customer session. OIDC for customers creates account lifecycle and IdP support burden.

Question 2: Should activation code be reusable?

Recommended answer: Default one-time. Allow limited reuse only when max_activations is explicitly set for a customer rollout.

Question 3: Should entitlement be package-level or version-level?

Recommended answer: Version-level. Package-level is too broad for customer delivery.

Question 4: Should project .npmrc contain auth tokens?

Recommended answer: No. Project .npmrc should contain registry routing only. Auth tokens stay short-lived.

Question 5: Should customer session mint npm tokens directly?

Recommended answer: Yes, but only install tokens, only for entitled package versions, and only with short TTL.

Question 6: Should delivery mean customer install permission?

Recommended answer: No. delivery is internal permission to prepare customer delivery artifacts and grants. Customer install is customer entitlement.

Implementation Status

Done:

customer/contact/entitlement/activation/session/device models and migration
staff customer management APIs behind FractalOps OIDC/customer_admin guard
customer activation/session/logout APIs
customer session token mint path for install-only npm tokens
Desktop customer activation command and form
Desktop customer install uses stored customer session before grant fallback
install guidance shows package/version, reinstall command, and .npmrc routing
audit events for customer upsert/contact/entitlement/activation/revoke/session logout
Nexus tarball enforcement for package_version and allowed_versions claims

Still recommended:

dedicated Customer Admin UI for staff-side customer/contact/entitlement management
project .npmrc writer/repair action instead of only showing guidance
Nexus metadata filtering if version list leakage becomes a product concern

Acceptance Criteria

• Staff can create a customer.
• Staff can assign package/version entitlement to that customer.
• Staff can issue and revoke activation codes.
• Customer can activate without FractalOps OIDC.
• Customer session is stored in OS secure store.
• Customer can install only entitled package versions.
• Customer cannot publish/build/deliver.
• node_modules delete plus reinstall still routes @yamon/* to protected registry.
• Project .npmrc contains no auth token.
• Nexus denies tarball downloads outside allowed_versions.
• Customer logout/revoke blocks future npm token minting.