Device tokens: reduce OAuth credential retention and membership-check amplification

[steipete]

Follow-up from the security review of #1199 (device pairing / read-only device tokens):

Each device-token record currently stores the owner's sealed GitHub OAuth credential for the full 90-day token lifetime, and every device-token request spends two uncached GitHub API calls for fail-closed membership revalidation. Three consequences worth improving:

• Credential at rest: the sealed OAuth credential's blast radius lives as long as the device token, not as long as the OAuth session.
• Rate-limit amplification: a busy device (or several) can burn meaningful GitHub API quota; membership checks could be cached briefly (e.g. 60s, still fail-closed on error) without materially weakening revocation latency.
• Silent early death: the device token nominally lasts 90 days but stops working whenever the stored OAuth grant expires or is revoked, which will read as a mystery failure on the device. Either surface a distinct error (pairing_reauth_required) or document the coupling.

None of this blocks the merged v1; it should be addressed before the iOS client (#778) ships broadly.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed July 31, 2026, 11:20 AM ET / 15:20 UTC.

Summary
Keep open for maintainer security review. The provided merged-PR context shows that 60-second fail-closed membership caching and the distinct pairing_reauth_required failure are already implemented, but it also explicitly says the sealed OAuth credential remains stored with the device-token record; changing that retention boundary needs an intentional design and migration decision.

Reproducibility: unclear. for a live failure, but medium-confidence source evidence is provided by the merged PR description: it explicitly says the sealed OAuth credential model remains unchanged while device tokens can last up to 90 days. Local current-main confirmation was blocked by the sandbox infrastructure failure.

Root-cause cluster
Relationship: canonical
Canonical: #1200
Summary: This is the canonical report for the device-token hardening work. The merged PR resolved the caching and reauthentication portions, while the remaining credential-retention boundary is distinct and still belongs here.

Members:

• partial_overlap: fix(worker): harden device token revalidation #1206 - Merged PR evidence covers request caching and a distinct reauthentication error but explicitly leaves the sealed OAuth credential model unchanged.
• adjacent_distinct: Implement v1 read-only Crabbox iOS coordinator companion #778 - The iOS companion scope depends on secure device-token behavior but does not itself specify the remaining durable-credential design.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Maintainer decision needed

Question	Recommendation
What durable authorization material, if any, may a long-lived device token retain to revalidate GitHub membership after the owner OAuth grant expires or is revoked?	Design a narrower revalidation credential: Define a least-privilege, independently expiring or renewable revalidation mechanism with explicit migration, revocation, and device recovery rules before implementation.

Why: The merged hardening deliberately leaves the sealed-grant model unchanged; selecting a replacement changes the authorization and revocation boundary rather than merely correcting an established implementation defect.

Next step
The remaining work requires a maintainer-approved security-boundary decision; automated repair must not choose a durable authorization or migration policy.

Review details

Best possible solution:

Adopt a documented device-token revalidation design that avoids retaining a reusable owner OAuth credential for the full device-token lifetime, preserves fail-closed membership checks and revocation semantics, and includes an explicit migration plus clear device-facing recovery behavior.

Do we have a high-confidence way to reproduce the issue?

Unclear for a live failure, but medium-confidence source evidence is provided by the merged PR description: it explicitly says the sealed OAuth credential model remains unchanged while device tokens can last up to 90 days. Local current-main confirmation was blocked by the sandbox infrastructure failure.

Is this the best way to solve the issue?

No: the merged cache and reauthentication work is the right fix for request amplification and silent expiry, but it intentionally does not decide how to reduce durable credential retention. A maintainer-approved security-boundary design is needed before a narrow implementation can be judged best.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• Replacing or shortening the stored grant without a defined alternative may make valid 90-day device tokens fail unexpectedly, weaken membership revocation guarantees, or require a durable-record migration.
• The checkout could not be inspected because the read-only sandbox failed before command execution, so the current-main implementation and ownership trail need a local source/history confirmation before an implementation plan is approved.

Codex review notes: model internal, reasoning high; reviewed against 5aa1c3983874.

Label changes

Label justifications:

• P2: This is a bounded security and reliability improvement in a recently merged device-token authorization flow, without evidence of an active bypass or data loss.
• impact:security: The central remaining concern is the at-rest lifetime and blast radius of a sealed OAuth credential.
• impact:auth-provider: The device authorization path depends on GitHub OAuth grant validity and organization/team membership checks.

Evidence reviewed

What I checked:

• Repository inspection unavailable: The only read-only inspection command failed before reading repository files or history with bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted; no local source, test, release, maturity-helper, or git-history claims are made from this checkout.
• Merged hardening covers two reported consequences: The provided context for merged PR fix(worker): harden device token revalidation #1206 states that it added a bounded 60-second successful-membership cache, retained fail-closed refresh behavior and immediate revocation precedence, and returns pairing_reauth_required for expired, unreadable, or rejected stored grants. (e31157d65ba5)
• Credential-retention concern remains explicitly unresolved: The same merged PR context says that the stored sealed OAuth credential model is unchanged, so it does not establish a fix for the requested reduction in credential-at-rest lifetime. (e31157d65ba5)
• Related mobile work is not a replacement: Open issue Implement v1 read-only Crabbox iOS coordinator companion #778 references this concern as a prerequisite before a broader iOS client rollout; it is a product-scope discussion rather than a canonical fix for device-token credential retention.

Likely related people:

• steipete: The supplied context attributes both the original device-pairing implementation and the merged revalidation hardening to this contributor, including the remaining sealed-grant model. (role: merged feature contributor; confidence: medium; commits: e1e5d143ef1f, e31157d65ba5; files: worker/src, worker/test, docs/features/device-pairing.md)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.