Add .NET 10 Razor Pages rewrite proposal with GitHub OAuth admin section and Aspire support

[Copilot]

Proposal to migrate downr from .NET Core 3.1 + Blazor WebAssembly to .NET 10 with pure Razor Pages (no Blazor Server/WebAssembly).

Changes

Added: PROPOSAL-DOTNET10-RAZOR-PAGES.md - Comprehensive rewrite proposal (2,291 lines) covering:

• Architecture shift: Blazor WebAssembly SPA → server-rendered Razor Pages

  • Single project (eliminate Client/Server/Shared split)
  • Direct data access from Page Models (eliminate API layer)
  • Server-side rendering for immediate content delivery

• Performance gains: 60-80% faster initial load (3-5s → 300-500ms)

  • No .NET runtime/assembly download (eliminates 2MB+ payload)
  • Output caching for rendered pages
  • Reduced bandwidth consumption

• SEO optimization: Full HTML in initial response (eliminate client-side rendering delay)

• Admin section (new optional feature - disabled by default):

  • Online Markdown editor with live split-pane preview
  • Post management dashboard with search/filter capabilities
  • Image upload functionality with drag-and-drop support
  • GitHub OAuth authentication (primary) with GitHub account integration
  • Static username/password authentication (alternative) from environment variables
  • Easy switching between authentication providers via configuration
  • Auto-save with error handling
  • Dual workflow support: Git+VS Code OR browser-based editing OR both
  • Comprehensive security guidance (CSP headers, secrets management, XSS mitigation, timing attack prevention)

• GitHub integration roadmap:

  • Phase 1 (Current): GitHub OAuth authentication with access token storage
  • Phase 2: Commit and push posts directly to GitHub repository from admin UI
  • Phase 3: GitHub repository as primary storage with automatic sync
  • Phase 4: PR-based workflows, branch management, webhooks

• .NET Aspire support (new optional feature for local development):

  • Optional AppHost and ServiceDefaults projects for enhanced developer experience
  • Aspire dashboard with logs, traces, metrics, and resource monitoring
  • Azure Storage emulator integration with one-line configuration
  • Easy service integration (Redis, databases, APIs) for future extensibility
  • Graceful degradation: app works perfectly without Aspire
  • Flexible deployment: Simple Linux App Service (recommended) OR full Aspire deployment to Azure Container Apps
  • Complete code examples with try/catch for optional Aspire features
  • OpenTelemetry observability (metrics, tracing, distributed logging)

• Migration strategy: 8-week sprint plan with phase-by-phase breakdown (Aspire integration optional in Sprint 8)

• Implementation patterns:

// Page Model replaces API + Blazor component
public class PostModel : PageModel
{
    private readonly PostService _postService;

    public Post Post { get; set; }
    public (Post Previous, Post Next) Navigation { get; set; }

    public IActionResult OnGet(string slug)
    {
        Post = _postService.GetPostBySlug(slug);
        if (Post == null) return NotFound();
        
        Navigation = _postService.GetPreviousAndNextPosts(slug);
        return Page();
    }
}

// Admin section - GitHub OAuth authentication setup
builder.Services.AddAuthentication()
    .AddGitHub(options =>
    {
        options.ClientId = builder.Configuration["downr:admin:github:clientId"];
        options.ClientSecret = builder.Configuration["downr:admin:github:clientSecret"];
        options.SaveTokens = true; // Save for future GitHub API calls
    });

// Aspire support - Optional AppHost configuration
var builder = DistributedApplication.CreateBuilder(args);
var storage = builder.AddAzureStorage("storage").RunAsEmulator();
var blobs = storage.AddBlobs("posts");
var web = builder.AddProject<Projects.downr_Web>("downr-web")
    .WithReference(blobs);
builder.Build().Run();

// Web app with graceful Aspire degradation
if (builder.Environment.IsDevelopment())
{
    try { builder.AddServiceDefaults(); }
    catch { /* Aspire not available, continue without it */ }
}

• Authentication features:

  • GitHub OAuth (recommended): Authenticate with GitHub account, validate authorized users, store access token for future GitHub API integration
  • Static credentials (alternative): Simple username/password from environment variables using BCrypt hashes, no external dependencies
  • Swappable via single configuration setting ("authProvider": "github" or "static")
  • Complete security hardening: fail-safe authorization, timing attack prevention, proper hash validation

• Package updates:

  • Remove Blazor dependencies
  • Add AspNet.Security.OAuth.GitHub for GitHub OAuth
  • Add BCrypt.Net-Next for static auth (optional)
  • Add Bootstrap Icons for admin UI
  • Add Octokit (future) for GitHub API integration
  • Add Aspire packages: Aspire.Hosting, Aspire.Hosting.Azure.Storage, OpenTelemetry packages (optional, Debug configuration only)
  • Update to .NET 10 SDKs

• Backward compatibility: Preserves content structure and configuration format

• Security: Production-ready security guidance including:

  • GitHub OAuth configuration validation
  • BCrypt password hash storage (not plaintext)
  • Constant-time comparison to prevent timing attacks
  • CSP headers with proper nonce generation
  • HTML sanitization
  • Secrets management best practices
  • Accessibility considerations
  • 13 comprehensive security considerations for both authentication providers

• Developer experience enhancements:

  • Run standalone with dotnet run (no Aspire required)
  • OR run with Aspire dashboard for enhanced observability
  • Visual dashboard for logs, traces, metrics, and health checks
  • One-click Azure emulator setup
  • Easy path to add databases, caching, or microservices in the future

Original prompt

Write a proposal for re-writing downr in .net 10. make sure it's all razor pages, with no blazor server anywhere in it.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[bradygaster]

@copilot Could you add to the proposal, support via an online markdown editor and, essentially, "admin section" where i could go and edit my posts?

[Copilot]

@copilot Could you add to the proposal, support via an online markdown editor and, essentially, "admin section" where i could go and edit my posts?

Added comprehensive admin section to the proposal (commit ba0a37b). The feature includes:

Core Features:

• Authentication with ASP.NET Core Identity
• Post management dashboard with search/filter
• Online Markdown editor with live preview
• YAML front matter form for metadata
• Image upload with drag-and-drop support
• Auto-save functionality

Technical Implementation:

• PostEditorService for CRUD operations
• Split-pane editor with real-time preview
• Markdown toolbar for quick formatting
• Security features (CSRF protection, rate limiting, input validation)

Key Design Decisions:

• Optional feature (disabled by default)
• Both Git + VS Code and admin UI workflows can coexist
• Respects same file structure (wwwroot/posts/{slug}/index.md)
• Configurable via appsettings.json

The admin section is covered in the new major section "Admin Section: Online Markdown Editor" with full implementation details, code examples, and updated migration phases.

[bradygaster]

@copilot Can you change it so the auth is github? i'd like to have the app support me logging into it with github. i'd like to make sure however we do the login, that future features like always keeping your content safe in a github repository would be a thing. i'm not too interested in other auth providers other than github and "static username and password stored in environment variables in the app" - and we should have both providers in this update and swapping them should be simple.

[Copilot]

@copilot Can you change it so the auth is github? i'd like to have the app support me logging into it with github. i'd like to make sure however we do the login, that future features like always keepi...

Updated authentication to use GitHub OAuth as the primary method with static credentials as an alternative (commit b3b7873).

GitHub OAuth Authentication (Primary):

• Authenticate using your GitHub account via OAuth
• Configure allowed GitHub usernames in appsettings
• Client ID and Client Secret stored in environment variables
• Access token saved for future GitHub API integration
• Setup: Create GitHub OAuth App, configure callback URL

Static Credentials (Alternative):

• Simple username/password from environment variables
• No external dependencies or OAuth setup required
• Suitable for air-gapped deployments or single-user scenarios
• Uses BCrypt password hashing

Easy Provider Switching:

• Change authProvider setting between "github" or "static"
• Each provider has its own configuration section
• Login UI automatically adapts to selected provider

Future GitHub Integration Roadmap:

• Phase 2: Commit and push posts directly to GitHub repo from admin UI
• Phase 3: Use GitHub repository as primary storage (sync on startup)
• Phase 4: PR-based workflow for drafts, branch management, webhooks
• Access token from OAuth enables all GitHub API operations via Octokit

The proposal now includes complete code examples for both authentication providers, security considerations specific to each, and a detailed roadmap for GitHub repository integration features.

[bradygaster]

@copilot could you update the proposal to include all of this?

[Copilot]

@copilot could you update the proposal to include all of this?

All requested features are already included in the proposal (commits ba0a37b through a616a21):

Admin Section (Lines 159-1244):

• Online Markdown editor with live split-pane preview
• Post management dashboard with search/filter
• Image upload with drag-and-drop
• YAML front matter form for metadata
• Auto-save functionality

Authentication (Lines 175-1002):

• GitHub OAuth as primary method (with setup instructions)
• Static username/password as alternative (from environment variables)
• Easy switching via authProvider configuration setting
• Complete implementation code for both providers

GitHub Integration (Lines 1192-1244):

• Phase 1: OAuth authentication with token storage (current)
• Phase 2: Commit/push posts to GitHub repo from admin UI (future)
• Phase 3: GitHub repository as primary storage (future)
• Phase 4: PR-based workflows and webhooks (future)

Security (Lines 1043-1178):

• 13 comprehensive security considerations
• GitHub OAuth validation and fail-safe authorization
• BCrypt password hashing for static auth
• Timing attack prevention
• CSP headers and XSS mitigation

The proposal is complete at 1,792 lines with all features documented, including technical implementation, code examples, configuration, and migration strategy.

[bradygaster]

@copilot Could you add to this support for it running locally using Aspire so folks could test it with Azure or if they wanted to add another db or some other integrations for deeper functionality, they could do so. ideally it could still deploy as easily as a small linux app service, but, if they wanted to deploy the full-on aspire thing, they could do that, too, to like, container apps or whatever. not worried about all that, yet, as much as i am just wanting to be able to run it like an aspire app and get all that goodness even though i don't plan on adding any apis or any back-end stuff or anything like that.

[Copilot]

@copilot Could you add to this support for it running locally using Aspire so folks could test it with Azure or if they wanted to add another db or some other integrations for deeper functionality, th...

Added comprehensive .NET Aspire support to the proposal (commit fec43cc). The integration provides enhanced local development while maintaining simple deployment options.

Key Features:

Local Development:

• Optional Aspire dashboard with logs, traces, metrics, and health checks
• Run with dotnet run on downr.Web (standalone) OR via AppHost for full dashboard experience
• Azure Storage emulator integration with one line of configuration
• Future-ready for adding Redis, databases, or other services

Project Structure:

• downr.AppHost - Aspire orchestration (optional, development-time only)
• downr.ServiceDefaults - Shared observability config (OpenTelemetry, health checks)
• downr.Web - Main app with graceful degradation (works with or without Aspire)

Deployment Flexibility:

• Simple: Deploy downr.Web to Linux App Service (no Aspire dependencies)
• Advanced: Deploy full Aspire solution to Azure Container Apps via azd up
• Aspire is completely optional - production deploys don't require it

Code Examples:

• Complete AppHost configuration with storage emulator
• ServiceDefaults with OpenTelemetry and resilience patterns
• Updated Program.cs with try/catch for graceful Aspire degradation
• Package references (Debug configuration only)

Benefits:

• Visual dashboard for monitoring during development
• Easy testing with Azure emulators
• One-line service additions (Redis, SQL, etc.)
• Future extensibility without architecture changes
• Standard deployment path unchanged

The proposal is now 2,291 lines with complete Aspire integration guidance.

[bradygaster]

@copilot i'd like you to implement all of this for me. what's our next step

[Copilot]

@copilot i'd like you to implement all of this for me. what's our next step

Implementing the complete proposal is a substantial undertaking that requires a phased approach. Here's the recommended path forward:

Recommended Next Steps:

Option 1: Proof of Concept Branch (Recommended)
Create a separate branch to build a working prototype with core features:

1. Set up basic .NET 10 Razor Pages structure
2. Migrate core post rendering (Index, Post pages)
3. Implement file-based content loading
4. Add RSS feed support
5. Verify it works end-to-end

This validates the architecture before full migration.

Option 2: Full Implementation Plan
If ready to commit to full rewrite, break into focused PRs:

• PR 1: New .NET 10 project structure + core services
• PR 2: Main Razor Pages (Index, Post, Category)
• PR 3: Admin section with GitHub OAuth
• PR 4: Static file migration + styling
• PR 5: Aspire integration (optional)

Option 3: Parallel Development
Keep current app running while building new version:

• Develop in /v2 directory or separate branch
• Migration can happen at your own pace
• Cut over when ready

Question for you:
Which approach fits your timeline and risk tolerance? I can start with Option 1 (POC) to validate the architecture quickly, or we can plan the full implementation if you prefer.

Note: This is a major rewrite (~3000+ lines of new code). The proposal serves as our blueprint, but implementation will take multiple iterations to do properly.

[bradygaster]

option 2 - burn it all down and start over. if there's ANY way we could save the content i've got in there - the markdown files with their metadata - that'd be great.