docs(specs): claude auth strategy — three-PR plan#155
Merged
Conversation
Add design specs for a three-PR series that replaces the copy-drift Claude OAuth forwarding path with a durable token-based auth contract backed by an operator-managed env resolver. - PR 1 (auth-sync-default): make sync the default, migrate copy configs in place with a deprecation notice, and drop the Copy variant from the enum. Fixes the 401-after-drift failure mode operators see today. - PR 2 (workspace-env-resolver): introduce four-layer env declarations (global / per-agent-class / per-workspace / per-workspace-x-agent) with scheme-dispatched values (literal / \$VAR / op://). Launch-time resolution via the 1Password CLI unlocks Touch-ID-gated secrets with no jackin-side storage. Partially delivers onepassword-integration.mdx option #2. - PR 3 (claude-token-auth-mode): add auth_forward = "token" as a thin consumer of PR 2's resolver. Requires CLAUDE_CODE_OAUTH_TOKEN in the resolved env; provisions .claude.json as {} and skips credentials forwarding so Claude Code's documented env-var precedence (takes priority over /login) applies cleanly. Delivers claude-auth-strategy.mdx option #3. Each spec is reviewable independently; PR 3 depends on PR 2. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
9472a90 to
d9e1757
Compare
This was referenced Apr 23, 2026
donbeave
added a commit
that referenced
this pull request
May 6, 2026
Add design specs for a three-PR series that replaces the copy-drift Claude OAuth forwarding path with a durable token-based auth contract backed by an operator-managed env resolver. - PR 1 (auth-sync-default): make sync the default, migrate copy configs in place with a deprecation notice, and drop the Copy variant from the enum. Fixes the 401-after-drift failure mode operators see today. - PR 2 (workspace-env-resolver): introduce four-layer env declarations (global / per-agent-class / per-workspace / per-workspace-x-agent) with scheme-dispatched values (literal / \$VAR / op://). Launch-time resolution via the 1Password CLI unlocks Touch-ID-gated secrets with no jackin-side storage. Partially delivers onepassword-integration.mdx option #2. - PR 3 (claude-token-auth-mode): add auth_forward = "token" as a thin consumer of PR 2's resolver. Requires CLAUDE_CODE_OAUTH_TOKEN in the resolved env; provisions .claude.json as {} and skips credentials forwarding so Claude Code's documented env-var precedence (takes priority over /login) applies cleanly. Delivers claude-auth-strategy.mdx option #3. Each spec is reviewable independently; PR 3 depends on PR 2. Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Claude <noreply@anthropic.com>
donbeave
added a commit
that referenced
this pull request
May 7, 2026
Add design specs for a three-PR series that replaces the copy-drift Claude OAuth forwarding path with a durable token-based auth contract backed by an operator-managed env resolver. - PR 1 (auth-sync-default): make sync the default, migrate copy configs in place with a deprecation notice, and drop the Copy variant from the enum. Fixes the 401-after-drift failure mode operators see today. - PR 2 (workspace-env-resolver): introduce four-layer env declarations (global / per-agent-class / per-workspace / per-workspace-x-agent) with scheme-dispatched values (literal / \$VAR / op://). Launch-time resolution via the 1Password CLI unlocks Touch-ID-gated secrets with no jackin-side storage. Partially delivers onepassword-integration.mdx option #2. - PR 3 (claude-token-auth-mode): add auth_forward = "token" as a thin consumer of PR 2's resolver. Requires CLAUDE_CODE_OAUTH_TOKEN in the resolved env; provisions .claude.json as {} and skips credentials forwarding so Claude Code's documented env-var precedence (takes priority over /login) applies cleanly. Delivers claude-auth-strategy.mdx option #3. Each spec is reviewable independently; PR 3 depends on PR 2. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Codex <codex@openai.com>
donbeave
added a commit
that referenced
this pull request
May 7, 2026
Add design specs for a three-PR series that replaces the copy-drift Claude OAuth forwarding path with a durable token-based auth contract backed by an operator-managed env resolver. - PR 1 (auth-sync-default): make sync the default, migrate copy configs in place with a deprecation notice, and drop the Copy variant from the enum. Fixes the 401-after-drift failure mode operators see today. - PR 2 (workspace-env-resolver): introduce four-layer env declarations (global / per-agent-class / per-workspace / per-workspace-x-agent) with scheme-dispatched values (literal / \$VAR / op://). Launch-time resolution via the 1Password CLI unlocks Touch-ID-gated secrets with no jackin-side storage. Partially delivers onepassword-integration.mdx option #2. - PR 3 (claude-token-auth-mode): add auth_forward = "token" as a thin consumer of PR 2's resolver. Requires CLAUDE_CODE_OAUTH_TOKEN in the resolved env; provisions .claude.json as {} and skips credentials forwarding so Claude Code's documented env-var precedence (takes priority over /login) applies cleanly. Delivers claude-auth-strategy.mdx option #3. Each spec is reviewable independently; PR 3 depends on PR 2. Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Claude <noreply@anthropic.com>
donbeave
added a commit
that referenced
this pull request
May 7, 2026
Add design specs for a three-PR series that replaces the copy-drift Claude OAuth forwarding path with a durable token-based auth contract backed by an operator-managed env resolver. - PR 1 (auth-sync-default): make sync the default, migrate copy configs in place with a deprecation notice, and drop the Copy variant from the enum. Fixes the 401-after-drift failure mode operators see today. - PR 2 (workspace-env-resolver): introduce four-layer env declarations (global / per-agent-class / per-workspace / per-workspace-x-agent) with scheme-dispatched values (literal / \$VAR / op://). Launch-time resolution via the 1Password CLI unlocks Touch-ID-gated secrets with no jackin-side storage. Partially delivers onepassword-integration.mdx option #2. - PR 3 (claude-token-auth-mode): add auth_forward = "token" as a thin consumer of PR 2's resolver. Requires CLAUDE_CODE_OAUTH_TOKEN in the resolved env; provisions .claude.json as {} and skips credentials forwarding so Claude Code's documented env-var precedence (takes priority over /login) applies cleanly. Delivers claude-auth-strategy.mdx option #3. Each spec is reviewable independently; PR 3 depends on PR 2. Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds design specs for a three-PR series that replaces the copy-drift Claude OAuth forwarding path with a durable token-based auth contract backed by an operator-managed env resolver.
auth-sync-default: makesyncthe default, migrate existingcopyconfigs in place with a one-line deprecation notice, drop theCopyvariant from the enum. Fixes the 401-after-drift failure mode from the claude-auth-strategy roadmap.workspace-env-resolver: introduce four-layer env declarations (global / per-agent-class / per-workspace / per-workspace × agent) with scheme-dispatched values (literal /$VAR/op://). Launch-time resolution via the 1Password CLI (Touch-ID gated byopitself) with zero jackin-side secret storage. Partially delivers option fix: resolve relative paths in workspace CLI arguments #2 from onepassword-integration.claude-token-auth-mode: addauth_forward = "token"as a thin consumer of PR 2's resolver. RequiresCLAUDE_CODE_OAUTH_TOKENin the resolved env; provisions.claude.jsonas{}and skips credentials forwarding so Claude Code's documented env-var precedence (wins over/login) applies cleanly. Delivers option chore: bump version to 0.5.0-dev #3 from the claude-auth-strategy roadmap.Each spec is reviewable independently. PR 3 has a hard dependency on PR 2 landing first; PR 1 is independent.
Specs in this PR
docs/superpowers/specs/2026-04-23-auth-sync-default-design.mddocs/superpowers/specs/2026-04-23-workspace-env-resolver-design.mddocs/superpowers/specs/2026-04-23-claude-token-auth-mode-design.mdWhat this PR is not
This PR contains design specs only. No Rust code, no config changes, no behavior changes. Each of the three PRs it describes will be opened separately once the design is approved.
Test plan
cargo fmt -- --check && cargo clippy && cargo nextest runop, hard error on missing env var, hard error on reserved-name overrideglobal → agent → workspace → workspace×agent, later wins)op readtimeout is acceptable (PR 2 spec)