Skip to content

Bluefly Authentication & Secrets Constitution

Status: Evergreen operating doctrine Scope: Workstations, agents, GitLab/CI, Oracle/runtime infrastructure, Kubernetes, DDEV, Composer, Git operations, and Bluefly applications.

1. Prime Directive

  • Authenticate once.
  • Reuse the authenticated session.
  • Reference secrets directly.
  • Never copy secrets.

If authentication becomes repetitive, agents begin searching for credentials, or secrets are copied between systems, the architecture is wrong. Stop the workaround. Fix the authentication path.

Bluefly does not build a second secret manager, credential broker, token cache, synchronization layer, or authentication abstraction when 1Password or the target platform already owns the capability.

AUTHENTICATE_ONCE=YES DO_NOT_WRAP_EVERY_CALL=YES SECRET_VALUES_IN_CHAT=NEVER SECRET_VALUES_IN_SOURCE=NEVER AGENT_SECRET_VISIBILITY=NO

Never print, inspect, export, persist, commit, log, screenshot, paste, echo, cache, or otherwise expose resolved secret values.

2. Authority Model

Authentication and authorization are different concerns. * AUTHENTICATION = proves identity * AUTHORIZATION = determines what that identity may do

The canonical model is: * Human authentication: 1Password * Machine authentication to secret infrastructure: 1Password * Secret storage: 1Password * Secret delivery: 1Password * Secret audit: 1Password * Secret references / naming: Bluefly * Authorization policy: Bluefly + target platform * Target credential creation: Target platform * Target credential authorization: Target platform * Target credential revocation: Target platform * Target credential rotation: Target platform * Runtime execution: Bluefly governed systems

The core rule: 1PASSWORD STORES AND DELIVERS. TARGET SYSTEMS AUTHENTICATE, AUTHORIZE, REVOKE, AND ROTATE THEIR OWN CREDENTIALS. BLUEFLY GOVERNS POLICY AND EXECUTION.

1Password access does not imply GitLab, Oracle, Kubernetes, Cloudflare, or other target authorization.

3. Canonical Authentication Flow

IDENTIFY PRINCIPAL ↓ AUTHENTICATE ONCE ↓ REFERENCE SECRET ↓ 1PASSWORD DELIVERS ↓ TARGET AUTHENTICATES / AUTHORIZES ↓ EXECUTE THROUGH OWNER ↓ REUSE AUTHORITY

Do not re-authenticate for every command. Do not wrap every git, glab, curl, composer, npm, API call, or tool call inside a new op run, op plugin run, or blu 1p run after the credential is already available to the intended process/session.

4. Human Workstations

Developer workstations use the official 1Password desktop application and CLI integration. Authentication occurs once and the existing authenticated session is reused. Preferred first check: op whoami Do not make this universal agent doctrine: eval "$(op signin)" (Interactive sign-in/bootstrap is environment-specific). Agents must not repeatedly prompt Thomas for biometric approval or authentication.

THOMAS_AUTHENTICATES_AS_THOMAS AGENTS_DO_NOT_BORROW_THOMAS_IDENTITY

5. Autonomous Agents

Standing autonomous agents must use their own machine or service identities. Examples: BLU, MAYOR-ORACLE, FOUNDRY, DRUPAL, REFINERY, SENTINEL, HARBORMASTER must not operate as Thomas.

Desired model: AGENT ↓ MACHINE / SERVICE IDENTITY ↓ SCOPED 1PASSWORD ACCESS ↓ TARGET-NATIVE IDENTITY / CREDENTIAL ↓ TARGET AUTHORIZATION

Required rule: THOMAS_CREDENTIALS_USED_BY_AGENTS=NO

If an agent lacks its own identity, classify: MACHINE_IDENTITY_PROVISIONING_GAP Do not solve that gap by borrowing Thomas's workstation session.

6. GitLab

GitLab owns GitLab authorization. 1Password stores and delivers the credentials or references used to access GitLab. The model is: 1PASSWORD ↓ GitLab credential/reference ↓ GITLAB ↓ GitLab authorization

Do not confuse 1PASSWORD_AVAILABLE with GITLAB_AUTHORIZED. A GitLab 401/403 does not automatically mean token expired, 1Password broken, or credential missing. Diagnose the actual layer.

Prefer, in order where appropriate: 1. CI_JOB_TOKEN 2. OIDC / workload identity 3. project/group/service identity 4. scoped service account 5. personal credential (only for human interactive work)

Shared CI authentication belongs in blueflyio/gitlab_components not copied into individual repositories.

7. GitLab CLI on Workstations

Use the already-configured approved GitLab authentication path. The intended pattern is: 1Password ↓ approved GitLab credential delivery ↓ glab ↓ reuse session/credential Do not repeatedly reconstruct a credential for every glab query. Do not create project-specific wrappers around GitLab authentication unless there is a proven upstream gap.

8. CI/CD

CI must be non-interactive. Use 1Password Service Accounts, official 1Password CI/CD integrations, GitLab-native workload identities, CI_JOB_TOKEN, or OIDC as appropriate. Never require interactive login, Thomas approval, desktop session, or copied workstation credentials. CI must not generate durable .env files containing secret values merely to move secrets between steps. Configuration should contain references, not secret values.

9. Oracle / Long-Lived Runtime

Oracle is runtime infrastructure. It is not a secret store. Long-lived Bluefly runtime should use approved machine-oriented mechanisms such as 1Password Connect, 1Password SDK, or approved service-account integration.

The target model is: APPLICATION ↓ semantic secret reference ↓ 1Password Connect / SDK / approved delivery ↓ secret exists only where runtime requires it

Do not copy workstation credentials onto Oracle. Do not leave plaintext credentials in shell profiles, compose files, Terraform variables, systemd units, repositories, documentation, or agent prompts.

10. Kubernetes

Use official 1Password mechanisms where appropriate: 1Password Kubernetes Operator, Secrets Injector, Helm integrations. Do not build a Bluefly-specific Kubernetes secret synchronization system when the official integration provides the required capability.

11. Secret References

Configuration contains semantic references, never resolved values. Preferred form: op://Vault/Item/field Use semantic aliases in application/configuration contracts (e.g., GITLAB_OPERATOR_TOKEN_REF, GITLAB_AGENT_TOKEN_REF, ORACLE_MACHINE_IDENTITY_REF). References may appear in documentation when needed. Resolved values never do. Do not globally export references or resolved credentials merely because they are documented.

12. Secret Exposure

If an agent discovers a credential in a file, DO NOT: cat it, print it, echo it, send it to BLU, send it to SENTINEL, paste it in chat, tell Thomas its value, store it in a Bead, or store it in a prompt. Instead report only: TARGET= PRINCIPAL= LOCATION= EXPOSURE_CONFIRMED= ROTATION_OWNER= AUTOMATED_ROTATION_AVAILABLE= Then execute the lifecycle through the correct owner.

13. Rotation

Credential rotation belongs to the target platform. Example for GitLab: EXPOSURE DETECTED ↓ IDENTIFY GITLAB PRINCIPAL ↓ GITLAB ROTATES / REVOKES ↓ UPDATE 1PASSWORD ↓ RELOAD CONSUMERS ↓ VERIFY NEW ACCEPTED ↓ VERIFY OLD REJECTED

Do not assume 1Password itself performs the target-system rotation. 1Password becomes the updated source of truth after the target credential lifecycle is completed.

14. Authentication Failure Algorithm

Before declaring AUTH_BLOCKED, an agent must: 1. Identify the operation and required principal. 2. Check existing authentication without creating a new session. 3. Use the already-configured authentication path. 4. Make one bounded authentication attempt. 5. Determine whether authentication succeeded. 6. If authenticated but denied, diagnose authorization (Identify the exact target-system denial). 7. Only then classify the blocker.

Report: OPERATION= PRINCIPAL= EXISTING_AUTH_PATH= ATTEMPT= AUTHENTICATED=YES|NO TARGET= TARGET_ROLE= AUTHORIZED=YES|NO EXACT_DENIAL=

15. Forbidden Patterns

Do not: * search vaults looking for a credential * enumerate secrets speculatively * print token values * copy credentials between systems * commit credentials * create plaintext secret files * create long-lived .env files containing secrets * put tokens into Git URLs * put secrets into composer auth files as durable state * create random PATs as debugging shortcuts * borrow Thomas's identity for autonomous agents * wrap every command in a fresh op invocation * create project-specific secret brokers * duplicate 1Password functionality * infer authorization from authentication * infer token expiration from one 401 call or 1Password unavailability

16. Agent Behavior

Agents should never need to understand the value of a secret. They need to know WHAT CAPABILITY IS REQUIRED, WHICH PRINCIPAL OWNS IT, WHICH REFERENCE IDENTIFIES IT, and WHICH TARGET AUTHORIZES IT. AGENTS_OPERATE_ON_REFERENCES_AND_CAPABILITIES, NOT_SECRET_VALUES.

17. Upstream-First Rule

When 1Password already provides integration (SDK, CLI, Connect, K8s, CI/CD), Bluefly configures and composes those capabilities, it does not reimplement them. Likewise, when the target platform provides token creation/rotation/revocation, use the native capability.

18. Separation of Duties

  • 1PASSWORD = secret system of record and delivery
  • BLUEFLY = naming, policy, orchestration, execution governance
  • TARGET PLATFORM = authorization and target credential lifecycle
  • AGENT = bounded consumer of capability
  • THOMAS = human operator, not machine credential broker

19. Fast Agent Preamble

BLUEFLY AUTH CONTRACT: 1Password authenticates and delivers secrets. Target systems authorize and rotate their credentials. Bluefly governs execution. Authenticate once. Reuse existing authority. Do not search for credentials. Do not enumerate vaults/items/tokens. Do not print, export, cache, copy, persist, commit, log, or paste secrets. Configuration contains references, never secret values. Human workstation: use existing authenticated 1Password / target session. Autonomous agent: use assigned machine/service identity. CI/CD: prefer native short-lived identity; otherwise approved 1Password Service Account. Oracle/runtime: use Connect / SDK / approved service-account delivery. Oracle is not a secret store. Before AUTH_BLOCKED report: OPERATION PRINCIPAL EXISTING_AUTH_PATH ATTEMPT AUTHENTICATED TARGET TARGET_ROLE EXACT_DENIAL. Never ask Thomas to paste a credential. Never create a PAT as a debugging shortcut. Never wrap every query in a new op run.

20. Constitutional Invariants

AUTHENTICATE_ONCE=YES REUSE_AUTHENTICATED_AUTHORITY=YES SECRET_SYSTEM_OF_RECORD=1PASSWORD TARGET_AUTHORITY=TARGET_PLATFORM HUMAN_SECRET_ROTATION_DEFAULT=NO AUTOMATED_ROTATION_DEFAULT=YES AGENT_SECRET_VISIBILITY=NO SECRET_VALUES_IN_CHAT=NEVER SECRET_VALUES_IN_SOURCE=NEVER THOMAS_IS_CREDENTIAL_BROKER=NO AGENTS_BORROW_THOMAS_IDENTITY=NO CUSTOM_SECRET_MANAGER=NO CUSTOM_AUTH_BROKER=NO DUPLICATE_1PASSWORD_FUNCTIONALITY=NO CONFIGURATION_CONTAINS_REFERENCES_ONLY=YES

Final Law AUTHENTICATE ONCE. IDENTIFY THE PRINCIPAL. REFERENCE THE SECRET. LET 1PASSWORD DELIVER IT. LET THE TARGET AUTHORIZE IT. EXECUTE THROUGH THE CORRECT OWNER. ROTATE THROUGH THE TARGET. UPDATE 1PASSWORD. RELOAD CONSUMERS. VERIFY. NEVER COPY THE SECRET. NEVER MAKE THOMAS THE MACHINE AUTHENTICATION LAYER.

21. 1Password MCP & AI-Readable Documentation

1Password publishes machine-readable documentation for agent consumption:

MCP Server (public, no auth required): https://www.1password.dev/mcp

Discoverable at: https://www.1password.dev/.well-known/mcp.json

Documentation Formats:

Format Coverage URL Best for
llms.txt Curated entry points https://www.1password.dev/llms.txt Orienting an AI, then fetching linked pages
llms-full.txt All published pages https://www.1password.dev/llms-full.txt Exhaustive coverage (requires large context)
Per-page .md One article Append .md to any article URL Specific topic lookup
MCP Search all published pages https://www.1password.dev/mcp Search and retrieve in agent sessions

Agent Integration: - Agents with MCP support should register the 1Password MCP server for documentation retrieval during sessions. - Agents without MCP should use https://www.1password.dev/llms.txt as the documentation entry point, fetching linked pages as needed. - Do not cache or persist documentation content beyond the active session.