AUTH_SCOPE

Purpose

Define what authentication and credential handling is and is not part of Harbor.

Harbor is an integration execution layer, not a general secret vault or machine credential manager.

Core Rule

A credential is in scope only when Harbor needs it to run a declared Harbor-managed integration.

If the credential is not tied to a specific integration, port, or action, it is probably out of scope.

In Scope

1. Harbor's own auth

Harbor may manage auth required to use Harbor itself.

Examples:

• Gateway admin auth
• UI login/session auth
• Node enrollment / node-to-gateway trust
• Future operator roles and permissions

2. Integration-bound credentials

Harbor may store or reference credentials required for a specific configured integration.

Examples:

• External API keys
• Bearer tokens for local HTTP services
• Webhook secrets
• Per-service auth headers
• Other scoped service tokens attached to a configured port

3. Local service auth through explicit integrations

Local services are acceptable only when modeled as explicit Harbor integrations.

Examples:

• A loopback HTTP API with a token
• A LAN service with a defined auth header
• A self-hosted service exposed through a configured port

Out of Scope

Harbor should not become a general-purpose credential or secret manager.

Examples:

• Linux or OS user passwords
• SSH private keys for general operator use
• Database passwords not tied to a Harbor-managed integration
• Filesystem secret discovery or crawling
• Reading arbitrary .env files, kubeconfigs, cloud creds, browser stores, or host config secrets
• Generic "run this with these creds" primitives
• Secret brokerage for tools unrelated to declared Harbor integrations

Good Fit

These usually fit Harbor well:

• Credentials attached to a specific configured port
• Hidden config values used only at execution time
• Least-privilege tokens
• Non-retrievable secrets
• Audited secret updates and use
• Clear policy around who can attach or replace secrets

Bad Fit

These usually indicate scope creep:

• Harbor storing arbitrary machine secrets
• Harbor exposing secret values in UI or API responses
• Harbor importing secrets from local files automatically
• Harbor becoming a reusable secret vault for unrelated tools
• Harbor enabling broad host or lateral access through shared credentials
• Harbor acting like a shell plus credential injector

Boundaries by Component

Gateway

Should do:

• Access control
• Policy
• Audit
• Node trust / enrollment

Should not do:

• Central secret browsing
• Collect arbitrary machine secrets
• Act as a generic secret broker

UI

Should do:

• Set secret
• Replace secret
• Show masked configured/not-configured state
• Show audit metadata such as last updated

Should not do:

• Reveal secret values
• Export secrets
• Display secret history in plaintext
• Browse local machine credentials

Node

Should do:

• Resolve integration-bound secrets at execution time
• Hold hidden config for declared integrations
• Use credentials only within policy and audit paths

Should not do:

• Act as a machine-wide secret warehouse
• Crawl for local secrets
• Store broad operator credentials for general reuse
• Provide arbitrary credential injection into unrelated tasks

Checks and Balances

Before adding any auth or credential feature, ask:

1. Is this required for Harbor itself to operate securely?
2. Is this required for a declared Harbor-managed integration?
3. Is the credential scoped to a specific port, service, or action?
4. Can it remain hidden and non-retrievable?
5. Can its use be audited?
6. Would this make Harbor look like a general secret manager?
7. Would compromise of this feature significantly widen blast radius?

If answers 1-5 are mostly yes and 6-7 are no, the feature may fit.

If not, it is likely scope creep.

Scope Creep Warnings

Reconsider the feature if it introduces any of the following:

• General local credential storage
• Secret discovery from disk or environment
• Reusable credentials not tied to an integration
• Secret reveal flows
• Broad host access or privilege pivoting
• Ambiguous ownership of who can view, rotate, or export secrets

Security Posture

Prefer:

• Least privilege
• Per-integration scoping
• Hidden config
• Runtime-only secret use
• Audit trails
• Minimal exposure in Gateway and UI

Avoid:

• Multi-purpose secret storage
• Plaintext visibility
• Shared high-privilege credentials
• Features that increase blast radius without strong need

Decision

Harbor should manage credentials only for:

• Harbor's own auth boundaries
• Explicit Harbor-managed integrations

Harbor should not manage arbitrary local machine, operator, or host credentials.

That boundary keeps the project focused, safer, and easier to reason about.