From 9b2367e2aa3420619c9a7b190ed6322c33e59a8d Mon Sep 17 00:00:00 2001 From: Tyler Gillispie Date: Fri, 21 Aug 2026 14:33:42 -0700 Subject: [PATCH] docs: add AGENTS.md guidelines and initial task kanban --- AGENTS.md | 19 ++++ tasks/GUIDELINES.md | 86 +++++++++++++++++++ tasks/META_PROMPT.md | 70 +++++++++++++++ ...at.auth-yes.seamless-3rd-party-sso-1609.md | 46 ++++++++++ 4 files changed, 221 insertions(+) create mode 100644 AGENTS.md create mode 100644 tasks/GUIDELINES.md create mode 100644 tasks/META_PROMPT.md create mode 100644 tasks/new/2026-0821.01.jul.feat.auth-yes.seamless-3rd-party-sso-1609.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0c703c2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,19 @@ +# AGENTS.md — Auth-Yes System Guidelines & Operating Protocol + +## 1. Project Context +Auth-Yes is a standalone, ultra-low-friction, zero-trust Identity and Access Management (IAM) fabric and WebAuthn Passkey authority. +- **Runtime:** Deno 2.x (TypeScript 5.x) +- **Architecture:** Modular Deno Workspace (`sdk/`, `server/`, `ui/`, `spire_ffi/`, `infra/`) +- **Web API & SSR:** Hono with pure Hono SSR JSX (Strictly React-free) +- **Workload Mesh:** ConnectRPC daemon + Rust SPIFFE/mTLS FFI crate (`spire_ffi/`) +- **Data Layer:** Dedicated PostgreSQL 18 + Valkey 8 (L1/L2 RESP3 Client Tracking) +- **Cookie Scope:** Wildcard `.atyg.org` domain scoping with host-collision sweep + +## 2. Key Architecture Standards +1. **Zero-Dependency SDK:** `@auth-yes/sdk` must remain 100% free of backend/database imports. ConnectRPC contracts live in `sdk/gen/`. +2. **Security:** Session invalidation and revocation MUST always be handled server-side (`deleteCookie` across host and wildcard domains). +3. **Quality Gates:** Every PR must pass `deno fmt`, `deno task lint`, `deno task check`, and `deno test`. + +## 3. History & Context Link +This repository was cleanly extracted from `ed-droid`. +- **Reference Conversation:** `conversation://6a3fa402-ae0a-4231-9991-b0ff79a61e0f` diff --git a/tasks/GUIDELINES.md b/tasks/GUIDELINES.md new file mode 100644 index 0000000..16e19f5 --- /dev/null +++ b/tasks/GUIDELINES.md @@ -0,0 +1,86 @@ +# Task Management Guidelines + +This document outlines the standard operating procedure for the repository-based +Kanban workflow using Markdown files to safely manage and track technical +stories, architectural planning, and audits. All agents and developers must +adhere to these guidelines. + +## A. The Filename Convention + +All task files MUST be Markdown (`.md`). The naming schema is strict and must +follow this exact format: + +`YYYY-MMDD.[sequence].[agent].[type].[scope].[short-description]-[HHMM].md` + +- **`YYYY-MMDD`**: The 4-digit year, a single hyphen, and the 4-digit month/day + (e.g., `2026-0820`). +- **`[sequence]`**: A 2-digit zero-padded number for the session's file order + (e.g., `01`, `02`). +- **`[agent]`**: The 3-letter author abbreviation (e.g., `jul`, `gem`, `tyl`). +- **`[type]`**: The work category, matching conventional commits (e.g., `story`, + `audit`, `fix`, `feat`, `sec`). +- **`[scope]`**: The specific architectural boundary or target component (e.g., + `setup-ts`, `auth-api`). +- **`[short-description]-[HHMM]`**: A kebab-case title followed by a single + hyphen and a 4-digit timestamp (hour and minute, e.g., `1702`) to guarantee no + filename collisions during simultaneous sessions. + +**Example:** `2026-0820.01.jul.feat.auth-api.add-rate-limiting-1702.md` + +## B. The Task Lifecycle (Kanban) + +Task status is determined **strictly by the file's directory location**, NOT its +name. + +- Files must **never** be renamed once created to preserve links and history. +- Files should **only** be moved at the absolute end of a work session. + +The directories and their purposes are: + +- **`tasks/new/`**: Where new tasks are generated. Work begins while the file + remains in this folder. +- **`tasks/wip/`**: This is strictly a parking lot. A file is only moved here at + the end of a session if the task could not be completed. +- **`tasks/complete/`**: Where the file is moved at the end of a session once + the work is successfully finished or the PR is merged. + +## C. The Required Metadata Header + +Every task markdown file must begin with this exact header structure: + +```markdown +# TASK METADATA + +- **Target Files:** [List of files involved] +- **Core Objective:** [1-sentence goal] +- **Dependencies:** [List any prerequisites or blockers] +- **Additional Important Notes:** [Any specific constraints, warnings, or + context] + +--- +``` + +## D. Mandatory Task File Structure + +Every technical story or feature task file MUST include the following sections +in this exact order: + +### 1. TASK METADATA + +The YAML/header block containing Target Files, Core Objective, Dependencies, and +Additional Notes. + +### 2. Architectural Considerations & Risks + +Before detailing any implementation steps, the authoring agent MUST analyze the +objective against the existing codebase and document: + +- **Risks:** Identify any potential regressions, security vulnerabilities, or + architectural anti-patterns this task might introduce. +- **Alternatives:** Explicitly state if a cleaner, more native, or highly + modular approach exists compared to the initial request. + +### 3. Proposed Implementation + +The structured phases, code extraction points, or execution steps required to +complete the task safely. diff --git a/tasks/META_PROMPT.md b/tasks/META_PROMPT.md new file mode 100644 index 0000000..192f45a --- /dev/null +++ b/tasks/META_PROMPT.md @@ -0,0 +1,70 @@ +**Intent of this file:** This file is intended for new-task-prompt development +and orchestrator templates. It is NOT for actual task research and creation. If +your current job is to create, plan, or format a task file, please refer to +`tasks/GUIDELINES.md` and ignore the templates in this file. + +--- + +# Orchestrator Meta-Prompts + +## 1. Task Planning Template (System Analyst) + +_Use this template to instruct an agent (such as Jules) to take a technical +idea, critically analyze the existing codebase, identify risks/alternatives, and +draft a compliant task file in `tasks/new/`._ + +```text +**Role:** Act as a System Analyst and Solutions Architect. Do not execute code or modify the codebase during this session. Your sole deliverable is to generate a task file in tasks/new/. + +**The Objective:** [State exactly what you want to achieve.] + +**Suggestions & Initial Thoughts:** +*Here is our starting hypothesis. Treat these as ideas to evaluate, not rigid requirements:* +* [Suggestion 1] +* [Suggestion 2] + +**Your Task:** +1. Research the codebase and analyze this objective against our current architecture. +2. Critically evaluate our suggestions: Do they make technical sense, or is there a cleaner, more native, or more modular approach? +3. Map out the `Target Files`, prerequisites/dependencies, and explicitly identify potential architectural risks, regressions, or friction. +4. Draft the task file in `tasks/new/` strictly adhering to the naming conventions, header metadata, and mandatory structure defined in `tasks/GUIDELINES.md`. +``` + +--- + +## 2. Implementation Execution Template (Developer) + +_Use this template when ready to command an agent to execute the work outlined +in an existing task file._ + +```text +**Role:** Act as an Implementation Engineer. + +**The Task:** Please review and execute the plan detailed in `[tasks/new/YYYY-MMDD.XX.agent.type.scope.title-HHMM.md]`. + +**Directives:** +1. Follow the strict 4-step state machine (Research -> Implementation -> Quality Gates -> Review). +2. Apply minimal, pure functional modifications. +3. Ensure all downstream pipeline steps and context contracts remain intact. +4. Run all quality gates (`deno fmt`, `deno task lint`, `deno task check`, `deno task test`). +5. Upon successful completion and verification, update the task status according to `tasks/GUIDELINES.md`. +``` + +--- + +## 3. Pre-PR Quality & Security Audit Template (Auditor) + +_Use this template to instruct an agent to perform an exhaustive pre-merge +audit._ + +```text +**Role:** Act as a Senior Security & Quality Assurance Auditor. + +**The Scope:** [List recent changes, PR branch, or target components to audit.] + +**Your Task:** +1. Inspect code changes against architectural boundaries. +2. Verify zero regression in authentication, session management, or RBAC grants. +3. Confirm all unit and integration tests pass with 0 lint warnings and 0 typecheck errors. +4. Document findings and generate an audit report if any vulnerabilities or performance bottlenecks are detected. +``` diff --git a/tasks/new/2026-0821.01.jul.feat.auth-yes.seamless-3rd-party-sso-1609.md b/tasks/new/2026-0821.01.jul.feat.auth-yes.seamless-3rd-party-sso-1609.md new file mode 100644 index 0000000..bb79a5c --- /dev/null +++ b/tasks/new/2026-0821.01.jul.feat.auth-yes.seamless-3rd-party-sso-1609.md @@ -0,0 +1,46 @@ +# TASK METADATA + +- **Target Files:** `auth-yes/server/db.ts`, `auth-yes/server/oidc.ts`, + `auth-yes/server/main.ts`, `auth-yes/ui/admin/integrations.tsx` (and related + UI files) +- **Core Objective:** Implement seamless 3rd-party SSO via a Zero-Click OIDC + Provider and Traefik ForwardAuth Header injection. +- **Dependencies:** Core Auth-Yes session mechanisms, Valkey cache, Hono + routing, React/JSX for UI. +- **Additional Important Notes:** Ensure OIDC logic is decoupled from `main.ts` + to prevent a monolith. Database migrations are required for OIDC + clients/authorization codes. + +--- + +### Phase 2: The Bonus Stage — Seamless 3rd-Party SSO (Gitea, Portainer, etc.) + +Your vision for frictionless 3rd-party access without double-logins is +achievable through two native patterns we can bring directly into auth-yes: + +#### 1. The "Zero-Click" OIDC Provider in auth-yes + +• Most self-hosted power tools (Gitea, Nextcloud, Grafana, Portainer, Proxmox, +Vaultwarden) support standard OpenID Connect (OIDC). • When auth-yes exposes +standard OIDC endpoints (/oauth/authorize, /oauth/token, /oauth/userinfo): • You +click "Login with Auth-Yes" on Gitea (or configure Gitea for auto-login). • +Gitea redirects to auth.atyg.org. • Because you already have your .atyg.org +passkey cookie active, auth-yes instantly authorizes and redirects back in ~10 +milliseconds without presenting any login dialogs. • Gitea automatically creates +and syncs your account on the fly. + +#### 2. Reverse-Proxy Header Authentication (Traefik ForwardAuth) + +• Apps like Gitea have native Reverse Proxy Auth +(ENABLE_REVERSE_PROXY_AUTHENTICATION = true). • When Traefik calls +/api/forward-auth, auth-yes injects X-Forwarded-User: . Gitea +immediately trusts the header and logs you in transparently with zero +interaction. + +#### 3. 3rd-Party App Integrations Manager in Admin Console + +• We can expand our Application Registry (/admin/apps) with an Integrations +Catalog (Client IDs, OIDC secrets, callback URLs, and role-mapping presets for +Gitea, Grafana, Portainer, etc.). • This gives you a single pane of glass to +manage passkey-secured SSO across your entire self-hosted ecosystem, allowing +you to optionally bypass Cloudflare Zero Trust popups entirely.