supercheck-io/supercheck / .agents/skills/security-auth
supercheck-security-auth
VerifiedWork on Supercheck authentication, RBAC and permission checks, tenant isolation and cross-organization or cross-project leaks, sessions, API, CLI and trigger keys, CLI device login, invitations, project membership, project variables, OAuth, super-admin and impersonation behavior, SSRF, or security-sensitive routes.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.7 KB |
SKILL.md
View on GitHub---
name: supercheck-security-auth
description: Work on Supercheck authentication, RBAC and permission checks, tenant isolation and cross-organization or cross-project leaks, sessions, API, CLI and trigger keys, CLI device login, invitations, project membership, project variables, OAuth, super-admin and impersonation behavior, SSRF, or security-sensitive routes.
---
# Supercheck security and authentication
```mermaid
flowchart LR
REQ[Cookie or bearer request] --> AUTH[Resolve identity]
AUTH --> SCOPE[Resolve organization/project]
SCOPE --> RBAC{Authorize exact action}
RBAC -->|allow| VALIDATE[Validate input]
VALIDATE --> QUERY[Scoped operation]
RBAC -->|deny| DENY[401 or 403]
```
## Start here
| File | Why |
|---|---|
| `app/src/lib/auth-context.ts` | `requireAuthContext()` resolves cookie or bearer identity plus organization/project; `AuthError`, `authErrorStatus()` give the 401/403 split |
| `app/src/lib/rbac/middleware.ts` | `hasPermissionForUser` (bearer-safe), `hasPermission` (session-only), `requirePermission`, `withProjectPermission`, `requireSuperAdmin` |
| `app/src/lib/rbac/permissions-client.ts` | Source of truth for resources, actions, and `Role` (`permissions.ts` mirrors it for Better Auth type inference) |
| `app/src/lib/security/` | `api-key-hash.ts` (token types and formats), `secret-crypto.ts`, `same-origin.ts`, `credential-owner.ts` |
| `app/src/app/api/jobs/route.ts` | Reference dual cookie/bearer route |
## Authentication
- Better Auth owns browser sessions, users, organizations, and membership. Do not add NextAuth patterns.
- Browser routes may use session cookies. CLI and API-key routes require bearer-compatible auth context.
- Never use a cookie-only permission helper in an API route that supports CLI bearer tokens: `hasPermission` and `requireProjectContext` read session state; use `requireAuthContext` with `hasPermissionForUser`.
- Permission checks use the effective (impersonated) user, not the admin who started impersonation. Credential-minting and similar sensitive actions must refuse under impersonation (`isImpersonatedSession` in `rbac/middleware.ts`), including revealing a secret value (403, audited as `secret_decrypt_impersonation_blocked`).
- Credentials whose owning user is suspended or gone must be rejected (`isCredentialOwnerActive`).
- Return `401` when identity is absent/invalid and `403` when an authenticated identity lacks permission.
- Permission failures from `AuthError` return `403`, never a hard-coded `401`. Status page unsubscribe links are signed tokens only (the legacy `unsubscribe_token` column was dropped in 0056) and subscriber webhook secrets exist only encrypted (`webhook_secret_encrypted`).
- Session cookies retain secure, HTTP-only, same-site, domain, expiration, revocation, and proxy-aware behavior.
- OAuth redirect URLs must exactly match provider configuration. GitHub applications require access to user email; Google requires configured consent and callback URLs.
## Roles, membership, and scope
- Read canonical resources, actions, and roles from `app/src/lib/rbac/permissions-client.ts`; never recreate role strings or a third permission matrix. When adding a resource or action, update `permissions-client.ts` and its mirror in `permissions.ts` together.
- Resolve tenant context before data access. IDs supplied by clients are selectors, not proof of ownership.
- Organization resources scope to the authenticated organization. Project resources additionally verify project ownership/membership.
- Project admins/editors require the applicable project membership relationship. Organization-wide privileges apply only through central RBAC rules.
- Invitations validate organization/project, role eligibility, normalized email, expiry, reuse/acceptance state, and inviter authority. Acceptance re-checks under a share lock that the inviter is still `org_owner` or `org_admin`, and refuses a `super_admin` with the generic `INVITE_ALREADY_USED` error; removing, demoting or leaving cancels the inviter's pending invitations (`cancel-pending-invites.ts`). The invite route must not reveal whether an address belongs to a platform administrator.
- Super-admin routes require explicit global-admin authorization and must not reuse ordinary tenant authorization as a shortcut.
- Security, membership, secret, administration, and billing mutations produce redacted audit events.
## API and trigger keys
- CLI/session API tokens (`sck_live_`/`sck_test_`) and job trigger keys (`sck_trigger_`, plus legacy `job_` formats) are different credential classes. Validate type, prefix/current format, expiry, enabled state, scope, and allowed operation.
- Store credential material according to the current one-time-display/hash design; never make plaintext recoverable through list/get APIs.
- Token lists expose safe metadata only. Creation returns a plaintext token only at the intended one-time boundary.
- Rate-limit authentication and credential-sensitive endpoints and return useful retry metadata where supported. The invite and API-key verification limiters fail closed: Redis down or slow (`withRedisDeadline`) returns `503` with `Retry-After`, never allows the request. AI analysis routes (job, k6, monitor) need `update` permission like AI fix, because they spend credits.
- Do not put tokens in repository config, URLs, logs, analytics, error messages, queue payloads, or client persistence beyond the intended secure store.
## Project variables and encryption
- Encrypt secret values server-side with the current scoped encryption context (single `SECRET_ENCRYPTION_KEY` with HKDF-derived per-context keys; no split-key configuration exists today).
- List/read APIs return redacted metadata for secrets. Decryption occurs only immediately before authorized isolated execution.
- Never enqueue decrypted variables or persist them in capacity/job payloads.
- File variables use the supported upload path and size/type controls. They are not serialized into CLI config.
- Playwright and k6 variable/file semantics differ. In k6, `readFile()` is unsupported; use `open(getFile('KEY'))` during init.
- Redact resolved secret values from stdout, stderr, execution logs, notifications, traces, and error objects.
## Input, browser, and network security
- Use shared Zod schemas and size/shape bounds for all untrusted data.
- User-controlled outbound URLs use the pinned-public-fetch/SSRF policy. Validate protocol, resolution, every redirect, and final connection target; block private/reserved ranges and metadata endpoints, including IPv4/IPv6 transition forms. There is no single helper; reuse the one for your layer:
- Worker probes and requests: `worker/src/common/utils/pinned-public-fetch.ts` (`fetchPublicEndpoint`), `pinned-monitor-request.ts`, `pinned-lookup.ts`.
- App AI SRE connectors: `app/src/lib/sre/connectors/pinned-fetch.ts`, `pinned-lookup.ts`, `endpoint-policy.ts`.
- App configuration-time URL checks: `app/src/lib/url-validator.ts` (shape and host only, no DNS pinning; pair it with execution-time pinning).
- Browser messages require `event.source`, exact parsed origin, allowed protocol/hostname, and schema-valid payloads. Use exact `targetOrigin`, never `*`, for privileged communication.
- Preserve CSRF, CSP, origin, proxy-header, upload, and response-field allowlisting protections.
- Provider/webhook signatures are verified before parsing side effects; webhook processing is idempotent and tenant-bound.
## Required negative tests
- Cross-organization and cross-project reads/writes.
- Cookie versus bearer callers for dual-auth routes.
- Wrong role/action, revoked/expired/wrong-type keys, reused invitations, and super-admin denial.
- Secret redaction in API output, logs, queues, and failures.
- SSRF through redirects, DNS rebinding, alternate IP forms, localhost/private/metadata targets.
- Forged browser origins/sources and malformed messages.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |