feat(cli,api): add skillx publish command with auth and ownership validation (#4)

- Add `skillx publish` CLI command (auto-detect git remote, --path, --scan, --dry-run)
- Secure Register API with authentication (API key or session)
- Validate GitHub repo ownership (require write access via collaborator permission API)
- Add path traversal protection on skill_path input
- Handle GitHub token expiry with clear error messages
- Create shared authenticate-request.ts helper (API key + session fallback)
- Create validate-repo-ownership.ts (GitHub permission check)
- Archive 3 completed/draft plans to plans/archived/
- Update docs (codebase-summary, system-architecture)

Author: mrgoonie

apps/web/app/lib/auth/authenticate-request.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared request authentication: try API key first, fallback to session.
+ * Returns userId or null if unauthenticated.
+ */
+
+import { getDb } from "~/lib/db";
+import { apiKeys } from "~/lib/db/schema";
+import { eq, and, isNull } from "drizzle-orm";
+import { verifyApiKey } from "./api-key-utils";
+import { getSession } from "./session-helpers";
+
+interface AuthResult {
+  userId: string;
+  method: "api-key" | "session";
+}
+
+export async function authenticateRequest(
+  request: Request,
+  env: Env,
+): Promise<AuthResult | null> {
+  // Try API key first (CLI usage)
+  const authHeader = request.headers.get("Authorization");
+  if (authHeader?.startsWith("Bearer ")) {
+    const apiKeyPlaintext = authHeader.substring(7);
+    const prefix = apiKeyPlaintext.substring(0, 8);
+
+    const db = getDb(env.DB);
+    const [foundKey] = await db
+      .select()
+      .from(apiKeys)
+      .where(and(eq(apiKeys.key_prefix, prefix), isNull(apiKeys.revoked_at)))
+      .limit(1);
+
+    if (foundKey) {
+      const isValid = await verifyApiKey(apiKeyPlaintext, foundKey.key_hash);
+      if (isValid) {
+        // Update last used timestamp (best-effort, may be dropped on Workers after response)
+        await db.update(apiKeys)
+          .set({ last_used_at: new Date() })
+          .where(eq(apiKeys.id, foundKey.id));
+
+        return { userId: foundKey.user_id, method: "api-key" };
+      }
+    }
+  }
+
+  // Fallback to session (web usage)
+  const session = await getSession(request, env);
+  if (session?.user?.id) {
+    return { userId: session.user.id, method: "session" };
+  }
+
+  return null;
+}

apps/web/app/lib/github/validate-repo-ownership.ts

@@ -0,0 +1,109 @@
+/**
+ * Validate that an authenticated user has access to a GitHub repository.
+ * Uses the user's GitHub OAuth access token from Better Auth account table.
+ */
+
+import { getDb } from "~/lib/db";
+import { account } from "~/lib/db/schema";
+import { eq, and } from "drizzle-orm";
+
+interface OwnershipResult {
+  valid: boolean;
+  reason?: string;
+}
+
+export async function validateRepoOwnership(
+  userId: string,
+  owner: string,
+  repo: string,
+  db: ReturnType<typeof getDb>,
+): Promise<OwnershipResult> {
+  // Look up GitHub account for this user
+  const [ghAccount] = await db
+    .select()
+    .from(account)
+    .where(and(eq(account.userId, userId), eq(account.providerId, "github")))
+    .limit(1);
+
+  if (!ghAccount || !ghAccount.accessToken) {
+    return {
+      valid: false,
+      reason: "No GitHub account linked. Please sign in with GitHub first.",
+    };
+  }
+
+  const githubUsername = ghAccount.accountId;
+
+  // Check if token might be expired
+  if (ghAccount.accessTokenExpiresAt) {
+    const expiresAt = new Date(ghAccount.accessTokenExpiresAt);
+    if (expiresAt < new Date()) {
+      return {
+        valid: false,
+        reason: "GitHub token expired. Please re-login with GitHub at https://skillx.sh/settings",
+      };
+    }
+  }
+
+  // Check if user is owner (fast path — username matches repo owner)
+  if (githubUsername.toLowerCase() === owner.toLowerCase()) {
+    return { valid: true };
+  }
+
+  // Check collaborator permission level via GitHub API (require write access)
+  try {
+    const res = await fetch(
+      `https://api.github.com/repos/${owner}/${repo}/collaborators/${githubUsername}/permission`,
+      {
+        headers: {
+          Authorization: `token ${ghAccount.accessToken}`,
+          Accept: "application/vnd.github.v3+json",
+          "User-Agent": "SkillX/1.0",
+        },
+      },
+    );
+
+    if (res.status === 401) {
+      return {
+        valid: false,
+        reason: "GitHub token expired. Please re-login with GitHub at https://skillx.sh/settings",
+      };
+    }
+
+    if (res.status === 404) {
+      return {
+        valid: false,
+        reason: `User "${githubUsername}" does not have access to ${owner}/${repo}.`,
+      };
+    }
+
+    if (res.status === 403) {
+      return {
+        valid: false,
+        reason: "GitHub token lacks permissions. Please re-login with GitHub.",
+      };
+    }
+
+    if (res.ok) {
+      const data = (await res.json()) as { permission: string };
+      const allowed = ["admin", "write"];
+      if (allowed.includes(data.permission)) {
+        return { valid: true };
+      }
+      return {
+        valid: false,
+        reason: `User "${githubUsername}" has "${data.permission}" access to ${owner}/${repo}. Write access required to publish.`,
+      };
+    }
+
+    return {
+      valid: false,
+      reason: `GitHub API returned ${res.status} when checking repo access.`,
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      reason: `Failed to verify repo ownership: ${error instanceof Error ? error.message : "unknown error"}`,
+    };
+  }
+}

apps/web/app/routes/api.skill-register.ts

@@ -14,8 +14,11 @@ import { eq } from "drizzle-orm";
 import { fetchGitHubSkill } from "~/lib/github/fetch-github-skill";
 import { scanGitHubRepo } from "~/lib/github/scan-github-repo";
 import { indexSkill } from "~/lib/vectorize/index-skill";
+import { authenticateRequest } from "~/lib/auth/authenticate-request";
+import { validateRepoOwnership } from "~/lib/github/validate-repo-ownership";
 
 const GITHUB_REPO_PATTERN = /^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/;
+const SAFE_PATH_PATTERN = /^[a-zA-Z0-9._\-/]+$/;
 
 interface RegisterBody {
   owner?: string;
@@ -26,6 +29,17 @@ interface RegisterBody {
 
 export async function action({ request, context }: ActionFunctionArgs) {
   try {
+    const env = context.cloudflare.env as Env;
+
+    // Require authentication
+    const auth = await authenticateRequest(request, env);
+    if (!auth) {
+      return Response.json(
+        { error: "Authentication required. Use API key (Authorization: Bearer) or sign in." },
+        { status: 401 },
+      );
+    }
+
     const body = (await request.json()) as RegisterBody;
     const { owner, repo, skill_path, scan } = body;
 
@@ -36,7 +50,25 @@ export async function action({ request, context }: ActionFunctionArgs) {
       );
     }
 
-    const env = context.cloudflare.env as Env;
+    // Validate skill_path if provided (prevent path traversal)
+    if (skill_path) {
+      if (skill_path.includes("..") || skill_path.startsWith("/") || !SAFE_PATH_PATTERN.test(skill_path)) {
+        return Response.json(
+          { error: "Invalid skill_path. Must be a relative path without '..' sequences." },
+          { status: 400 },
+        );
+      }
+    }
+
+    // Validate GitHub repo ownership
+    const db = getDb(env.DB);
+    const ownership = await validateRepoOwnership(auth.userId, owner, repo, db);
+    if (!ownership.valid) {
+      return Response.json(
+        { error: ownership.reason || "You do not have access to this repository." },
+        { status: 403 },
+      );
+    }
 
     // Mode: specific skill_path → register single subfolder skill
     if (skill_path) {

docs/codebase-summary.md

@@ -11,7 +11,8 @@ skillx/
 │       │   ├── components/            # React UI components (14 files)
 │       │   ├── lib/
 │       │   │   ├── db/                # Drizzle ORM schema + database helpers
-│       │   │   ├── auth/              # Better Auth config + session helpers
+│       │   │   ├── auth/              # Better Auth config + session helpers + authenticate-request
+│       │   │   ├── github/            # GitHub API utilities + validate-repo-ownership
 │       │   │   ├── search/            # Hybrid search orchestration (5 modules)
 │       │   │   ├── vectorize/         # Embedding indexing (3 modules)
 │       │   │   └── cache/             # KV caching utilities
@@ -70,6 +71,7 @@ skillx/
 | `api.skill-install.ts` | API | ? | Track skill install (fire-and-forget) |
 | `api.usage-report.ts` | API | 99 | Log skill execution outcomes |
 | `api.user-api-keys.ts` | API | 133 | Create/list/revoke API keys |
+| `api.skill-register.ts` | API | ? | Register/publish skills from GitHub repos (auth required) |
 | `api.admin.seed.ts` | API | 121 | Load demo seed data |
 | `$.tsx` | Catch-all | 23 | 404 page |
 
@@ -140,12 +142,22 @@ skillx/
 | `auth-client.ts` | React client for sessions (getSession, signIn, signOut) |
 | `session-helpers.ts` | `getSession(request, env)`, `requireAuth()` — request-level auth |
 | `api-key-utils.ts` | Hash/verify API keys (SHA-256), generate prefixes |
+| `authenticate-request.ts` | Unified auth: tries API key first, fallbacks to session; returns `{ userId, method }` |
 
 **Flow:**
 1. User clicks "Sign in with GitHub"
 2. Better Auth → GitHub OAuth → session cookie (7d expiry)
 3. Routes check: `const session = await getSession(request, env)`
 4. Protected routes: `await requireAuth(session)` → 401 if missing
+5. For dual-auth endpoints (CLI + Web): `const auth = await authenticateRequest(request, env)` → try API key, fallback to session
+
+### GitHub Integration (apps/web/app/lib/github)
+
+| Module                       | Purpose |
+|------------------------------|---------|
+| `validate-repo-ownership.ts` | Verify user has write access to GitHub repo (used by skill registration) |
+
+**Used by:** Register API to validate author owns the GitHub repository before publishing skills.
 
 ### Vectorization (apps/web/app/lib/vectorize)
 
@@ -169,6 +181,7 @@ skillx/
 | `index.ts` | - | Commander.js CLI entry + command registration |
 | `commands/search.ts` | 86 | `skillx search "..."` → API call → table output |
 | `commands/use.ts` | 78 | `skillx use skill1 skill2` → fetch SKILL.md, POST install, echo to stdout |
+| `commands/publish.ts` | 183 | `skillx publish [owner/repo]` → register/publish skills from GitHub |
 | `commands/report.ts` | 90 | `skillx report` → POST usage metrics to API |
 | `commands/config.ts` | 91 | `skillx config set/get KEY VALUE` → local store |
 | `lib/api-client.ts` | 35 | HTTP client with API key auth |
@@ -179,7 +192,10 @@ skillx/
 npm install -g skillx-sh
 skillx search "data processing"
 skillx use skillx-search skillx-email
-skillx config set SKILLX_API_KEY sk_...
+skillx publish owner/repo                    # Auto-detect or explicit owner/repo
+skillx publish owner/repo --path path/to/skill --scan
+skillx publish --dry-run
+skillx config set api-key sk_...
 skillx report --outcome success --duration 1234
 ```
 

docs/system-architecture.md

@@ -281,6 +281,7 @@ Response:
 | POST | `/api/skills/:slug/review` | Write review |
 | POST | `/api/skills/:slug/favorite` | Add/remove favorite |
 | POST | `/api/skills/:slug/install` | Track install (fire-and-forget) |
+| POST | `/api/skills/register` | Register/publish skills from GitHub repo (validates write access) |
 | POST | `/api/report` | Report usage |
 
 ### User Endpoints (Session Only)
@@ -298,6 +299,59 @@ Response:
 |--------|------|---------|
 | POST | `/api/admin/seed` | Load demo data (dev only) |
 
+## Skill Registration (Publish) API
+
+**Endpoint:** `POST /api/skills/register`
+
+**Authentication:** Required (API key or session)
+
+**Request Body:**
+```json
+{
+  "owner": "github-username",
+  "repo": "repo-name",
+  "skill_path": "path/to/skill",      // optional: specific skill subfolder
+  "scan": true                         // optional: scan entire repo for SKILL.md files
+}
+```
+
+**Validation:**
+- User must authenticate (API key or session)
+- GitHub repo ownership verified (write access required)
+- Scans repo for SKILL.md files at specified path or root
+- Falls back to repo-wide scan if single skill not found
+
+**Response (single skill):**
+```json
+{
+  "skill": {
+    "slug": "owner-skill-name",
+    "name": "Skill Name",
+    "author": "github-username",
+    "description": "..."
+  },
+  "created": true
+}
+```
+
+**Response (multi-skill scan):**
+```json
+{
+  "skills": [
+    { "slug": "owner-skill-1", "name": "...", "author": "..." },
+    { "slug": "owner-skill-2", "name": "...", "author": "..." }
+  ],
+  "registered": 2,
+  "skipped": 1
+}
+```
+
+**Status Codes:**
+- 200: Success
+- 401: Unauthenticated
+- 403: No write access to GitHub repo
+- 404: No SKILL.md files found
+
 ## Deployment Architecture
 
 ```