Skip to content

Latest commit

 

History

History
17 lines (16 loc) · 4.76 KB

AGENTS.md

File metadata and controls

17 lines (16 loc) · 4.76 KB

Authentication template

  • This repository is a standalone public-ready template. It must install, test and deploy independently. Never add sibling imports, private repository URLs, local development paths, production identifiers or automatic synchronization with another repository.
  • Keep one authentication implementation in src/auth.ts and the common Hono app in src/gateway.ts. Provider files are thin entry points: cloudflare/index.ts for Workers, src/index.ts for native Vercel Hono, src/node.ts for the shared Node Request handler with explicit runtime environment mapping, and netlify/functions/auth.ts for a modern Node Request-to-Response function behind the forced root-route rewrite in netlify.toml. Netlify is not Deno Edge; Vercel explicitly selects hono in vercel.json.
  • Use Node 24 and pnpm 11.7.0. Keep the npm package private: true and the license Apache-2.0. Avoid framework scaffolding, extra adapters, new abstractions and code comments unless they explain a necessary constraint.
  • Keep GH_CLIENT_ID, GH_CLIENT_SECRET, AUTH_SECRET and SITE_ORIGIN required runtime configuration. ALLOWED_ORIGINS is optional: blank enables public destination confirmation; an exact comma-separated allowlist restricts destinations and skips confirmation. Reject malformed lists and wildcard origins. Origins must be canonical HTTPS, with explicit HTTP localhost development as the only exception. Reject HTTP 127.0.0.1 and IPv6 origins.
  • Ship only an all-blank .env.example. Keep local secrets, keys, .env and .dev.vars unread and out of commits; request no secret values in chat. AUTH_SECRET is independently generated cryptographic material of at least 32 characters, not a GitHub credential. Secrets belong only in the gateway's hosting runtime.
  • Preserve GitHub App expiring user tokens, S256 PKCE, encrypted/authenticated HttpOnly host-only cookies, bounded expiring state, same-origin CSRF-protected confirmation and exact opener origin/source/nonce checks. Keep the callback at exactly SITE_ORIGIN/callback. Installation-time OAuth stays off, Setup URL blank and webhooks off; no private key is needed for this user-token flow.
  • Installation/repository grants and user authorization are separate. A user token covers the intersection of user access and App installation permissions, potentially across multiple repositories. Neither an origin allowlist nor an editor repository picker makes it a repository-scoped token. Document only the permissions the selected backend needs.
  • Preserve callback CSP, popup opener compatibility and hardened response headers. Never add wildcard postMessage targets, permissive CORS or a callback-state bypass. /refresh stays bodyless, same-origin and CSRF-protected. Cross-origin editors reopen login at expiry; there is no automatic cross-origin renewal. Stateless cookies do not provide persistent replay tracking or concurrent refresh serialization.
  • Keep refresh tokens out of browser JavaScript. Document editor storage separately: Rigel RC1 stores the access-token session in localStorage. Do not claim memory-only storage or silently change editor behavior while editing gateway documentation.
  • Retain no telemetry, analytics or request-URL logging. Never log callbacks, codes, tokens, cookies or provider response bodies. Keep Cloudflare observability disabled. Review provider/proxy logs separately on every host; do not promise that Netlify or Vercel platform logs are universally disabled.
  • Use pnpm check, pnpm test and pnpm test:browser for verification. Tests use synthetic credentials and mocked GitHub transport; the browser suite uses native Chrome. pnpm build only typechecks; providers handle bundling. Keep generated browser profiles and scratch artifacts in ignored _temp/.
  • Local commands are pnpm dev:cloudflare (8789), pnpm dev:netlify (8888, pinned Netlify CLI 27.14.2, offline) and pnpm dev:vercel (3000, pinned Vercel CLI 65.2.0). Match local SITE_ORIGIN and a development App callback to the selected port.
  • Report synthetic tests, live provider deployment, real GitHub login, repository access and save/readback as separate results. Do not claim an untested host works. Do not commit, push, publish or deploy without explicit authorization.
  • Keep README registration and deployment instructions aligned with actual entry points, scripts and current official provider documentation. Use example.com placeholders. Generate deploy buttons with pnpm buttons only after the actual public repository URL is known; never invent a remote or active button. pnpm test:platform GATEWAY_ORIGIN EDITOR_ORIGIN checks routing and security without following GitHub redirects.
  • Operators need their own legal identity, privacy notice and terms. This template does not extend Rigel's hosted-service policy to an adopter's deployment.