Docs / Commercial And Brand

Commercial And Brand

Agent Token Security Plan

Add **Node-local agent tokens** so Harbor Node can require a real credential for network action calls and attach those calls to a stable per-agent identity.

commercial and brandagenttokensecurityplan

Source: AGENT_TOKEN_SECURITY_PLAN.md

Agent Token Security Plan

Summary

Add Node-local agent tokens so Harbor Node can require a real credential for network action calls and attach those calls to a stable per-agent identity.

This should unlock:

per-agent or per-integration credentials
per-agent permissions
cleaner audit attribution
better approval attribution
token revocation and deletion
future per-agent rate limits and policy overlays

This plan is intentionally Node-local first. It should not depend on Cloud, Fleet, billing, or the public website.

Why This Matters

Today Harbor Node accepts action execution requests on the local API without a first-class Node-issued bearer credential model.

Relevant current wiring:

live action execution happens at apps/harbor-node-api/src/index.ts on POST /v1/actions/:actionId/execute
the current route trusts requestedBy from the request body and writes that into audit and approval records
approvals and audit already exist and are good places to attach a stronger caller identity
Harbor UI already shows audit and approval behavior, so this feature can integrate into an existing operator surface instead of inventing one from scratch

This means we can add a real auth layer without replacing Harbor Guard, Harbor audit, or the action model.

Security Position

Do not use an 8 to 10 character bearer token for real network auth.

Recommended structure:

agentId: short, human-friendly identifier for UI and logs
token name: human-friendly label such as Claude Desktop, OpenCode Agent, or Nightly Gmail Worker
secret token: random opaque bearer token, one-time reveal only

Recommended secret length:

minimum: 16 random characters
preferred MVP: 20 to 24 random characters

Recommended storage:

store only a token hash
optionally store a short fingerprint for UI display
never log the raw token
never return the raw token after creation

Scope

In Scope For Pass 1

Node-local token storage in SQLite
create / list / revoke / delete token management
one-time secret reveal UI
token hashing and verification
permission scopes on the token
protect remote action execution with bearer token auth
use resolved token identity in audit and approval records
basic last-used tracking

Explicitly Out Of Scope For Pass 1

Cloud sync of tokens
website account token management
Fleet-wide token replication
org / team management
token expiry policies
IP allowlists
OAuth for agents
signed request schemes
mTLS
broad auth across every Harbor route

Current Wiring Notes

Execution route

Current execution is handled in apps/harbor-node-api/src/index.ts.

Current behavior:

- local audit events - approval records - optional cloud activity sync metadata

route: POST /v1/actions/:actionId/execute
request body includes requestedBy
route writes requestedBy into:

Existing attribution model

Shared caller and audit shapes already exist in packages/shared/src/index.ts.

This is useful because we do not need to invent a whole new audit model. We can resolve the token into a stable HarborActor and feed that into the existing system.

SDK

The SDK in packages/sdk-ts/src/index.ts already centralizes requests and can be extended later with optional bearer token support for headless agents.

Proposed Model

Agent profile

Add an optional agent profile concept.

Purpose:

group one or more tokens under one logical agent identity
allow better audit naming
allow future per-agent policy and limits

Fields:

agentId
name
description?
status
createdAt
updatedAt

Recommended MVP:

start with agent profiles present in the model
token creation requires linking to one profile
allow one token per agent as the normal path

Agent token

Fields:

tokenId
agentId
name
permissions
tokenHash
tokenFingerprint
createdAt
lastUsedAt?
revokedAt?
status

Token secret format:

opaque random bearer string
optional prefix for recognition such as hn_

Example:

hn_A7f2mPq91Lx4Vr8K

Permission model

Start route-based, not hyper-granular.

Recommended MVP permissions:

actions.execute
actions.read
ports.read
approvals.read
approvals.resolve
audit.read
settings.read

Do not start with dozens of fine-grained per-action scopes.

If later needed, add:

per-port scopes
per-category scopes
read-only versus execute-only subsets

Data Model

Add SQLite tables in apps/harbor-node-api/src/store.ts.

`agent_profiles`

Columns:

agent_id TEXT PRIMARY KEY
name TEXT NOT NULL
description TEXT
status TEXT NOT NULL
created_at TEXT NOT NULL
updated_at TEXT NOT NULL

`agent_tokens`

Columns:

token_id TEXT PRIMARY KEY
agent_id TEXT NOT NULL
name TEXT NOT NULL
permissions_json TEXT NOT NULL
token_hash TEXT NOT NULL
token_fingerprint TEXT NOT NULL
status TEXT NOT NULL
last_used_at TEXT
revoked_at TEXT
created_at TEXT NOT NULL
updated_at TEXT NOT NULL

Indexes:

idx_agent_tokens_agent_id
idx_agent_tokens_status

Foreign key:

agent_id -> agent_profiles.agent_id

API Design

Add shared contracts in packages/shared/src/index.ts.

Management routes

GET /v1/agent-profiles
POST /v1/agent-profiles
GET /v1/agent-tokens
POST /v1/agent-tokens
POST /v1/agent-tokens/:tokenId/revoke
DELETE /v1/agent-tokens/:tokenId

Creation response:

return token metadata
return plaintext token once

List response:

- name - linked agent - permissions - created - last used - status - fingerprint

no plaintext token
show:

Authenticated execution routes

Pass 1 should require bearer token auth for:

POST /v1/actions/:actionId/execute

Pass 1 can optionally protect more read routes later, but action execution is the important first boundary.

Bearer format:

Authorization: Bearer <token>

Behavior:

missing token -> 401
invalid token -> 401
revoked token -> 403
missing permission -> 403

Execution Flow

Token creation

Operator opens Token Manager in Harbor UI.
Operator creates or selects an agent profile.
Operator chooses token name and permissions.
Harbor generates a secret token.
Harbor stores only the hash and metadata.
Harbor shows the secret once in a modal.
Operator copies it into the target agent environment.
After modal close, the secret is gone.

Action execution

Agent sends bearer token in Authorization header.
Harbor verifies token hash.
Harbor resolves token to agent profile and permissions.
Harbor maps that into requestedBy.
Harbor checks token permission.
Harbor runs existing Harbor Guard policy.
Harbor writes audit / approval / cloud activity using the resolved token identity.