Skip to content

CLAUDE.md

Latest commit

 

History

History
102 lines (79 loc) · 9.85 KB

CLAUDE.md

File metadata and controls

102 lines (79 loc) · 9.85 KB
Raw

std-agent 类型速查

本项目的 AI 配置由 stdagent 管理，分为 5 种类型：

  • rules - 自动加载的编码 / 操作规范。AI 在 session 开始就遵守。
  • skills - 按需触发的能力包（遵循 Agent Skills 标准）。AI 看到 description 匹配用户意图时主动调用。
  • commands - 用户输入 /command-name 触发的模板。AI 不主动调用。
  • references - 背景参考资料。AI 仅在需要时查阅，不自动加载。
  • subagents - 隔离子代理定义。AI 通过 spawn 子进程或 CLI 调用执行。

源文件在 .stdai/standards/<type>/<name>.md。用 stdagent which <file> 查文件触发的规则集。用 stdagent explain 查类型详细语义。

XID Identity Platform

XID is a multi-tenant identity platform on Cloudflare, MIT licensed (Copyright 2026 StringKe). Self-hosting gets the full feature set: no tiering, no license check. Scope = Clerk DX + Auth0/Zitadel (OIDC IdP, org model) + WorkOS (SSO federation, directory sync). One codebase serves single-tenant and multi-tenant; the difference is configuration, never stripped-out code.

apps/server is the identity Core: protocols, APIs, admin logic, Hosted Auth and account UI. Binding-free frontend Workers are separate: Nimbus Site (apps/site) owns apex, www and public docs; Console (apps/console) owns management UI under /console. Hosted sign-in and consent stay in Core because an RP redirects unauthenticated users to /authorize.

Sources of truth

  • Product design: docs/design/, chapters 00-08. Change design there before implementation.
  • Shipped support level is NOT design intent: protocol status docs/protocols/source-map.md and gap-audit.md, SDK maturity docs/sdks/platform-matrix.md. Never report local L0-L3 evidence as production-supported.
  • Directory tree, kernel-vs-SDK package split, authoritative applyTo globs: reference xid-repo-layout -- read before placing a new file or writing an applyTo entry.
  • Runtime, binding / DO / queue names, cron schedules, pinned libraries, rejected alternatives: reference xid-tech-stack -- read before choosing a library or naming a binding.

Global iron rules

Binding summaries; long form with paths and rationale: reference xid-iron-rules-detail.

  1. TenantContext is the single source: issuer, signing keys, RPID and policy come from it, never from a module-level singleton.
  2. Tenant isolation by injection (P0): D1 has no RLS, so every query goes through the Drizzle tenant layer injecting tenant_id (plus org_id). No raw-SQL bypass, no admin path reusing business APIs, cross-tenant tests mandatory.
  3. Crypto boundary: never implement primitives -- Web Crypto, plus @noble/hashes for Argon2id. Protocol and business logic in-house; SAML XML-DSig uses a library.
  4. Signing key isolation: the default issuer signs with a per-instance ES256 key, envelope-encrypted under the Workers Secrets KEK. Plaintext private keys are NEVER persisted, and instance_signing_keys is the only signing source.
  5. Zero protocol shortcuts: PKCE S256 only, exact redirect_uri, rotating refresh with family revocation, state/nonce, single-use codes, jti replay defense, four WebAuthn checks.
  6. All i18n through lingui: SPA, React SDK and Worker API errors MUST NOT hardcode user-visible strings; transactional email is the documented exception.
  7. Enumeration resistance: every auth endpoint returns one uniform opaque response, timing normalized by constant-time comparison plus jitter.
  8. Platform admin is ManagerAssignment: one console driven by manager_assignments. Do not build a separate admin tenant, app, API or RBAC.

AI configuration

Sources live in .stdai/standards/; CLAUDE.md / AGENTS.md / .claude/ / .agents/ are generated by stdagent sync, MUST NOT be hand-edited, and MUST be committed. Workflow: reference stdagent-config-workflow.

Imported Rules

下列条目由 stdagent 同步生成到 .claude/rules/，AI 工具读到 @<path> 自动加载，AI 也可通过 description 提示判断是否相关：

  • @.claude/rules/cloudflare-bindings.md -- Cloudflare binding roles - D1 relational, Durable Objects for strong consistency, KV cache, R2 objects, Queues async, plus audit / email / metering pipeline invariants (applyTo: apps/server/worker/**/*.ts, wrangler.toml, wrangler.jsonc, **/durable-objects/**/*.ts)
  • @.claude/rules/code-style.md -- TypeScript quality baseline: file and function size limits, naming, type safety (no any, no enum, type over interface), named exports, Workers runtime constraints (applyTo: **/*.ts, **/*.tsx)
  • @.claude/rules/crypto-boundary.md -- Crypto primitives come from Web Crypto and are never hand-written; protocol and business logic are in-house; SAML XML signing uses xmldsigjs (applyTo: packages/crypto/**/*.ts, packages/protocol/**/*.ts, packages/webauthn/**/*.ts, packages/saml/**/*.ts)
  • @.claude/rules/error-handling.md -- Never swallow errors; throw typed AppError and let Hono onError map it, return Result for expected failures, validate boundaries with valibot, never leak internals, no floating promises (applyTo: **/*.ts)
  • @.claude/rules/i18n-lingui.md -- lingui for Site, Core UI, Console, shared UI, React SDK and Worker errors; email stays on Mustache (applyTo: apps/server/src/**/*.tsx, apps/server/src/**/*.ts, apps/console/src/**/*.tsx, apps/console/src/**/*.ts, apps/site/src/**/*.astro, apps/site/src/**/*.ts, packages/web-ui/**/*.tsx, packages/web-ui/**/*.ts, packages/react/**/*.tsx, packages/i18n/**/*.ts, apps/server/worker/lib/locale.ts, apps/server/worker/lib/errors.ts, apps/server/worker/middleware/i18n.ts, apps/server/worker/middleware/error.ts, lingui.config.ts)
  • @.claude/rules/monorepo-toolchain.md -- Monorepo ownership: pnpm owns dependencies, turborepo is the only cross-package orchestrator, Vite+ (vp) owns lint/format/test/packaging, standard Vite owns app builds (applyTo: pnpm-workspace.yaml, turbo.json, vite.config.ts, **/package.json, **/vite.config.ts)
  • @.claude/rules/oidc-oauth.md -- OIDC/OAuth2 protocol correctness as an IdP - mandatory PKCE S256, exact redirect_uri match, refresh rotation with family revocation, token claims, DPoP, PAR (applyTo: packages/protocol/**/*.ts, apps/server/worker/oidc/**/*.ts, apps/server/worker/oauth/**/*.ts)
  • @.claude/rules/password-auth.md -- Argon2id only, HIBP breach detection, reset / OTP / backup secrets stored as hashes only, pepper never in D1, MFA factor and step-up rules (applyTo: apps/server/worker/auth/**/*.ts, apps/server/worker/me-auth/**/*.ts, apps/server/worker/me/password.ts, apps/server/worker/me/mfa-factors.ts)
  • @.claude/rules/signing-keys.md -- Instance ES256 signing keys with envelope encryption (KEK in Workers Secrets), multiple concurrent kids, four-step rotation (applyTo: packages/crypto/**/*.ts, apps/server/worker/oidc/**/*.ts, apps/server/worker/crons/**/*.ts)
  • @.claude/rules/tenant-context.md -- TenantContext is the single source of issuer / signing keys / RPID / policy; the default issuer is always the instance issuer (applyTo: apps/server/worker/**/*.ts, packages/protocol/**/*.ts, packages/crypto/**/*.ts, packages/db/**/*.ts)
  • @.claude/rules/tenant-isolation.md -- D1 has no RLS - isolation is enforced by the Drizzle scoped query layer injecting tenant_id/org_id, no ad-hoc SQL in handlers, cross-tenant tests required (P0) (applyTo: packages/db/**/*.ts, apps/server/worker/**/*.ts)
  • @.claude/rules/webauthn.md -- WebAuthn verification with no skip path, UV required, residentKey required, sign_count clone detection, per-tenant RPID subdomain (applyTo: packages/webauthn/**/*.ts, apps/server/worker/auth/passkey*.ts, apps/server/worker/me-auth/passkey*.ts, apps/server/worker/me/passkeys.ts, apps/server/worker/durable-objects/challenge-store.ts, apps/server/src/routes/sign-in/passkey.ts, apps/server/src/routes/sign-in/usePasskeySignIn.ts)
  • @.claude/rules/anti-abuse.md -- Three-layer abuse prevention (Cloudflare Rate Limiting / Turnstile / RateLimitStore Durable Object), fail-closed rate limiting, constant-time account enumeration protection (applyTo: apps/server/worker/auth/**/*.ts, apps/server/worker/me-auth/**/*.ts, apps/server/worker/middleware/**/*.ts, apps/server/worker/lib/rate-limit.ts, apps/server/worker/lib/verify-rate-limit.ts, apps/server/worker/durable-objects/rate-limit-store.ts)
  • @.claude/rules/api-sdk-conventions.md -- Management API conventions (/v1/ prefix, cursor pagination, sk_live_ keys, shared auth guards), structured XidAPIError, webhook events, SDK networkless verification (applyTo: apps/server/worker/**/admin/**/*.ts, apps/server/worker/**/v1/**/*.ts, packages/core/**/*.ts, packages/backend/**/*.ts, packages/react/**/*.tsx)
  • @.claude/rules/git-commit.md -- Conventional Commits 1.0.0 message format, mandatory DCO sign-off, and the ban on rewriting pushed history (applyTo: **/*)
  • @.claude/rules/testing.md -- vitest conventions - AAA structure, descriptive names, mandatory coverage of protocol / tenant isolation / password / token / enumeration paths, negative paths, no placeholder tests (applyTo: **/*.test.ts, **/*.test.mjs, **/*.spec.ts)
  • @.claude/rules/utils-abstraction.md -- Rule of three before extracting a helper, pure functions with no side effects, topic-named modules instead of a utils dumping ground, D1 access only through the tenant query layer (applyTo: **/*.ts, **/*.tsx)

About This File

This file is part of stdagent synchronized AI standards.