archy/docs/nostr-git-source-hosting.md

# Nostr Git Source Hosting Plan

This plan describes how Archipelago can publish and accept contributions to its
source code through `ngit`, NIP-34, and GRASP while keeping the developer
experience inside Archipelago.

## Goals

- Publish Archipelago source from a sanitized, fresh-history repository.
- Make the in-app registry the primary onboarding path for contributors.
- Let contributors clone, branch, push PR branches, open PRs, and discuss issues
  with a Nostr identity from their Archipelago node.
- Follow the Bitcoin Core development model: broad public review and easy forks,
  with canonical merge authority held by a small maintainer set.
- Give contributors full read, fork, and proposal rights, but no direct merge
  rights on the canonical repository.
- Keep the official maintainer identity and merge authority separate from user
  node identities.

## Current Building Blocks

Archipelago already has most of the primitives needed for this:

- App manifests and the app registry already install developer tooling as
  rootless Podman apps.
- The `gitea` app provides a conventional fallback Git UI and package registry.
- The app launcher already exposes a consent-gated NIP-07 bridge for launched
  apps using `getPublicKey`, `signEvent`, NIP-04, and NIP-44 requests.
- The backend exposes node and identity Nostr signing RPC methods.
- FIPS gives nodes a stable mesh identity and private transport path, but repo
  announcements and PRs should remain NIP-34 compatible on normal Nostr relays.
- DWN protocol registration exists and can be used later for local contribution
  metadata/cache, but should not be required for the first public workflow.

## Protocol Basis

Use existing Nostr Git conventions rather than inventing an Archipelago-only
protocol:

- NIP-34 repository announcement events identify repositories with kind `30617`.
- NIP-34 repository state events publish branch/tag refs with kind `30618`.
- NIP-34 patches, pull requests, PR updates, issues, and status events use kinds
  `1617`, `1618`, `1619`, `1621`, and `1630`-`1633`.
- `ngit` provides the `git-remote-nostr` helper for `nostr://` clone URLs and PR
  branches.
- GRASP servers provide Git Smart HTTP storage while Nostr events remain the
  authority for repository identity, refs, PRs, issues, and maintainer state.

Primary references:

- https://nips.nostr.com/34
- https://docs.rs/crate/ngit/latest/source/README.md
- https://ngit.dev/grasp/

## Recommended Architecture

### Apps

Create two first-party apps:

- `ngit`: CLI/runtime package containing `ngit` and `git-remote-nostr`.
- `archipelago-source`: web UI for cloning Archipelago source, viewing NIP-34
  issues/PRs, opening branches, and submitting PR events.

The `archipelago-source` app should depend on `ngit`. It can also recommend
Gitea for users who want a conventional local web Git UI, but Gitea should not
be the source of truth for public contribution permissions.

### Contributor Onboarding

When the user installs `archipelago-source` from the registry:

1. Show a modal before first launch: "Contribute to Archipelago".
2. Explain that the app will use their Archipelago Nostr identity to clone and
   sign contribution events.
3. Display the maintainer repository announcement, clone URL, maintainer npub,
   and relay/GRASP endpoints.
4. Ask for consent to:
   - fetch repository metadata from configured relays,
   - clone source through `nostr://`,
   - create local branches,
   - sign NIP-34 issue/PR/comment events,
   - push PR branches to approved GRASP servers.
5. Store approval per app origin, identity id, repository id, and relay set.

This should build on the existing NIP-07 app-launcher bridge, but use a more
specific permission scope than the generic sign-event approval.

### Identity And Permissions

Use four identity classes:

- `archipelago-maintainer`: an offline or tightly controlled Nostr key that
  signs the canonical kind `30617` repo announcement and status/merge events.
- `archipelago-merge-maintainer`: one of the small set of maintainer npubs
  allowed to advance canonical refs and publish valid merged/applied status.
- `archipelago-build`: release automation key for signed release artifacts and
  CI status events. It must not have merge authority.
- `contributor`: user node or app-specific identity used for PRs, issues, and
  comments.

Contributor rights:

- Clone the repository.
- Open issues.
- Push proposal branches using `pr/<npub>/<short-topic>` or `pr/<event-id>`.
- Publish NIP-34 PR/update/comment events.
- Rebase and update their own PR branch.
- Run local validation and attach status evidence.

Contributor restrictions:

- Cannot update `refs/heads/main` or release branches in canonical state.
- Cannot publish maintainer-valid merge/applied status.
- Cannot alter the canonical repository announcement.
- Cannot publish release catalog signatures.

Maintainer rights:

- Publish/update the canonical repo announcement.
- Publish canonical `refs/heads/main` state.
- Mark PRs merged/closed/draft via NIP-34 status events.
- Sign release tags and catalog updates.

Fork rights:

- Any contributor can create their own NIP-34 kind `30617` repository
  announcement for a fork.
- Fork announcements should use the NIP-34 `u` tag to point back to the
  canonical `archy` repository.
- The source app should make forking a first-class path: "Fork on Nostr", clone
  the fork locally, push branches to the contributor's GRASP list, and open PRs
  back to canonical Archipelago when they want review.
- Forks can have their own maintainer npubs, relays, policies, and release
  cadence, but the app should clearly label them as forks unless signed by the
  canonical maintainer set.

The GRASP server policy should enforce this by accepting pushes to maintainer
refs only when backed by signed maintainer state, while allowing contributor PR
refs from their own npubs.

## Repository Layout

Canonical repo announcement:

- repo id: `archy`
- display name: `Archipelago`
- clone URLs:
  - `nostr://<maintainer-npub>/<relay-hint>/archy`
  - `https://<grasp-host>/<maintainer-npub>/archy.git`
- relays:
  - Archipelago-operated relay
  - at least two public Nostr relays that support the event load
- GRASP servers:
  - Archipelago-operated GRASP instance
  - one public GRASP-compatible mirror

Keep the existing HTTP Git remote as a mirror during launch. The docs can
present `nostr://` as the preferred contribution path once the workflow is
proven.

## UI Requirements

The source app should provide:

- A first-run contribution modal with a real Archipelago source graphic, not a
  generic text-only dialog.
- Current clone status and local path.
- Branch list, changed files, commit form, and push/open-PR flow.
- PR inbox, issue list, maintainer status, and relay health.
- Explicit identity indicator showing which npub will sign events.
- A merge rights indicator that clearly says contributors can propose changes
  but cannot merge them.
- A fork flow that creates a user-owned NIP-34 repo announcement and remote,
  then offers "Open PR to Archipelago" from any fork branch.
- Maintainer badges based only on pinned canonical maintainer npubs, not relay
  metadata or server-side account names.
- Links to container docs, deployment docs, manifest spec, and open-source
  readiness tasks.

## Backend Work

Add an RPC module for source contribution workflow:

- `source.repo-info`: returns canonical announcement, clone URL, relay set,
  maintainer npubs, and local clone state.
- `source.ensure-ngit`: verifies the `ngit` app/runtime is installed.
- `source.clone`: clones or updates the local source checkout.
- `source.status`: returns branch, dirty files, ahead/behind, and PR state.
- `source.commit`: creates a local commit from selected files.
- `source.fork`: creates a contributor-owned NIP-34 fork announcement and local
  remote.
- `source.open-pr`: pushes a PR branch and publishes a kind `1618` event.
- `source.update-pr`: updates the branch and publishes kind `1619`.
- `source.issue`: publishes a kind `1621` event.

Backend must shell out through a narrow command wrapper, never arbitrary user
commands. The wrapper should set an isolated working tree under
`/var/lib/archipelago/source/archy`, run as the Archipelago service user, and
deny operations outside that path.

## Security Model

- Never expose maintainer private keys to an Archipelago node.
- Prefer app-specific contributor identities over the node's default identity.
- Require per-action consent for first PR push, issue creation, and signing any
  event that tags the canonical repository.
- Pin the canonical maintainer npub in the app manifest and backend config.
- Keep the canonical merge-maintainer allow list signed by the
  `archipelago-maintainer` key; never infer merge rights from GRASP server
  accounts.
- Verify the canonical kind `30617` event signature before displaying clone
  instructions.
- Treat GRASP servers as untrusted storage; verify Git refs against signed
  Nostr state.
- Do not use destructive git operations from the UI without an explicit modal.
- Store local clones and generated patches outside app container writable roots
  unless the user exports them.

## MVP

1. Package `ngit` as a first-party app.
2. Stand up one Archipelago-operated GRASP server and one Nostr relay.
3. Publish sanitized fresh-history `archy` through `ngit init`.
4. Add a simple `archipelago-source` app that clones source and links out to the
   preferred Nostr Git browser.
5. Add app-launcher consent scopes for repository-specific NIP-34 signing.
6. Allow issues and PR branch submission from contributor npubs.
7. Add a one-click fork flow that publishes a contributor-owned fork
   announcement referencing canonical Archipelago.
8. Keep maintainer merge/status publication manual.

## Later

- Native PR review UI with file diffs and inline comments.
- CI status events signed by the build identity.
- FIPS-first source sync between trusted Archipelago nodes.
- Private prerelease repositories using NIP-42 allow lists and/or protected
  events if the ecosystem support is mature enough.
- Multi-maintainer policy with threshold signatures or explicit maintainer-list
  rotation events.

## Open Questions

- Which maintainer npub should become canonical for `archy`?
- Should contributor identities be node-default or app-specific by default?
- Which GRASP implementation should be deployed first: `ngit-grasp` or another
  NIP-34/GRASP-compatible relay?
- Should the source app include a full web Git UI in v1, or launch Gitea/ngit
  browser links for review while keeping signing/submission native?
- What exact license and contribution certificate should contributors accept
  before submitting PR events?