escapeboy/claude-code-kit/onepassword-integrate

1Password Integration & Compatibility Skill

Note on `references/`: the stack-specific recipes referenced at the bottom are companion files you author per stack (the progressive-disclosure layout from guide.md). The detection and audit phases below are complete without them.

Bring any project to maximum-depth 1Password integration in two layers:

• Backend (secret resolution) — let the team store one Service Account token and reference everything else as op://vault/item/field. No more secrets in .env files, CI variables, or code.
• Frontend (site compatibility) — make every auth form play perfectly with 1Password autofill, strong-password generation, passkeys, and the W3C /.well-known/change-password URL.

When to Use (and When NOT to)

Operating principles

1. Always refresh docs first. 1Password ships SDK/CLI changes monthly. Never trust training data — pull the current developer portal before recommending anything.
2. Detect before deciding. Run the detection phase even if the user says "we don't have it yet" — the user's belief is often wrong (a dependency, a CI step, or a colleague may have wired part of it).
3. Greenfield only when nothing exists. If even partial integration exists, audit + improve rather than rebuild — much cheaper for the user.
4. Stack matches matter more than depth. A perfect Go install is useless to a Laravel team. Pick the stack first, then the depth.
5. Defense in depth on the frontend. Adding autocomplete="current-password" is free; not adding it silently breaks autofill. Always ship the full set.
6. Never write a Service Account token to disk. Tokens live in env vars passed to op (or the SDK). Tokens in .env files committed by accident are a recurring incident pattern.

Phase 1 — Refresh 1Password developer docs (mandatory first step)

Pull the current state of the developer platform via web search/fetch. Always include the current year in the queries.

Required reads — capture these into working memory before doing anything else:

Also pull these standards:

• W3C /.well-known/change-password: <https://w3c.github.io/webappsec-change-password-url/>
• WHATWG autofill tokens (HTML autocomplete spec): <https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill>
• WebAuthn Level 3 (relevant for passkeys-as-2FA): <https://www.w3.org/TR/webauthn-3/>

Document any deltas vs. training data the user should know about.

Phase 2 — Detect what's already wired up

Run these scans against the current project. Treat any positive hit as "integration exists, audit don't replace".

2.1 Stack detection

Run in this order, stop at the first match:

If multiple match (monorepo), pick the closest to the user's current working directory.

2.2 Existing-integration markers

Grep the project (skip vendor/, node_modules/, .git/, dist/, build/) for any of:

1password|onepassword|1Password|OnePassword
op://
OP_SERVICE_ACCOUNT_TOKEN
OP_CONNECT_HOST|OP_CONNECT_TOKEN
@1password/sdk|onepassword-sdk|github.com/1Password/onepassword-sdk-go
.well-known/change-password

For each hit, classify:

• Backend wiring — driver class, resolver service, env injection.
• Frontend wiring — autocomplete attrs, well-known routes, passkey form.
• CI/CD wiring — op run --env-file or similar.
• Doc-only mention — README / docs but no code.

2.3 Auth-form audit

Find all login / register / reset-password / forgot-password / password-update / 2FA-challenge forms — look in:

• Laravel: resources/views/auth/*, Livewire profile components
• Next.js: app/login/**, app/register/**, app/(auth)/**, pages/login.*, etc.
• Rails: app/views/sessions/, app/views/registrations/, app/views/passwords/, Devise overrides.
• Generic: any file matching *login*, *register*, *password* with <input type="password">.

For each, check:

2.4 Site-compat surface

Check whether these endpoints exist and respond correctly:

Phase 3 — Decide: audit or install

After Phase 2, classify the project:

3a — Greenfield install

For the detected stack, implement:

1. Credential storage — type/enum addition for "1Password Service Account", encrypted at rest, validated against ^ops_.{28,}$.
2. Resolver — a service shelling out to op read --no-newline (or using the SDK) with the token in env (never argv).
3. CLI install — Dockerfile or CI step that pins a known op version with checksum.
4. Env-injection point — wherever the project launches subprocesses or builds env for workers, swap raw env vars for op:// references resolved at launch.
5. Frontend hygiene — apply §3c patches.
6. Tests — unit test fakes op CLI to assert: token in env not argv, malformed reference rejected, exit-code-1 surfaces stderr.

For each step, write the change or open a sub-task. Run the test suite afterwards. Never declare done without all green tests + a working op vault list smoke test in the target environment.

3b — Audit + improve existing backend

For each existing surface, check the safety invariants:

1. Token never in argv (use OP_SERVICE_ACCOUNT_TOKEN env). ps-leak is real.
2. Token validation: starts with ops_ AND length >= 32.
3. Reference grammar enforcement: 3 segments, no .., no shell metas ($, ` `, ;, &, |, <, >, ()`, whitespace).
4. Resolver returns trimmed output (rtrim($val, "\r\n")) — --no-newline flag is best-effort across op versions.
5. op CLI pinned to a specific version (with SHA256 ideally) in the runtime image.
6. Service Account scope is documented for users — encourage narrow scopes.
7. No op calls from web request handlers — only from queue workers / async contexts (web has tighter timeouts and loses output buffering).
8. Logs never include the resolved value.
9. op:// reference tokens themselves CAN be logged (they're not secrets) — useful for audit trails.
10. Connect Server, if used, runs as a separate service with its own access token AND 1password-credentials.json mounted read-only.

For each violation, propose a minimal-diff fix and ship it. Do not rewrite the whole driver if only one invariant is broken.

3c — Frontend hygiene patch

Always-safe patches (apply unconditionally — none of them break working autofill):

1. Login form → add autocomplete="username" + autocomplete="current-password".
2. Register form → add autocomplete="name", autocomplete="username", autocomplete="new-password" ×2.
3. Reset-password form → ensure autocomplete="username" + autocomplete="new-password" ×2.
4. Password-update form → add hidden <input type="text" name="username" autocomplete="username" value="{{ user.email }}" hidden aria-hidden="true" tabindex="-1"> companion.
5. 2FA TOTP code → autocomplete="one-time-code" + inputmode="numeric".
6. 2FA recovery code → autocomplete="off" (NOT one-time-code).
7. New /.well-known/change-password route → 302 to the actual password-change UI, exempt from auth middleware (so password managers can probe without logging in).
8. passwordrules attribute on signup password fields (match server policy).
9. Any third-party-secret input field → autocomplete="off" data-1p-ignore="true".

Always add a regression test (one per stack) asserting autocomplete="..." strings appear in rendered output.

Phase 4 — Report & wrap up

Produce a single-paragraph summary plus a checklist of what was found/changed per layer (backend / frontend / tests / outstanding manual steps).

Always finish with one of: