9.4 KiB

Raw Blame History

Git Credential Helper for GitRepublic

This guide explains how to use the GitRepublic credential helper to authenticate git operations (clone, fetch, push) using your Nostr private key.

Overview

GitRepublic uses NIP-98 HTTP Authentication for git operations. The credential helper automatically generates NIP-98 authentication tokens using your Nostr private key (nsec).

Setup

1. Make the script executable

chmod +x scripts/git-credential-nostr.js

2. Set your NOSTRGIT_SECRET_KEY environment variable

Important:

This is YOUR user private key (for authenticating your git operations)
Never commit your private key to version control!

# Option 1: Export in your shell session
export NOSTRGIT_SECRET_KEY="nsec1..."

# Option 2: Add to your ~/.bashrc or ~/.zshrc (for persistent setup)
echo 'export NOSTRGIT_SECRET_KEY="nsec1..."' >> ~/.bashrc
source ~/.bashrc

# Option 3: Use a hex private key (64 characters)
export NOSTRGIT_SECRET_KEY="<your-64-char-hex-private-key>"

# Note: The script also supports NOSTR_PRIVATE_KEY and NSEC for backward compatibility

3. Configure git to use the credential helper

Important: The credential helper must be called for EACH request (not just the first one), because NIP-98 requires per-request authentication tokens. Make sure it's configured BEFORE any caching credential helpers.

Global configuration (for all GitRepublic repositories):

# Add our helper FIRST (before any cache/store helpers)
git config --global credential.helper '!node /absolute/path/to/gitrepublic-web/scripts/git-credential-nostr.js'

# Optional: Disable credential caching to ensure our helper is always called
git config --global credential.helper cache
# Or remove cache helper if you want to ensure fresh credentials each time:
# git config --global --unset credential.helper cache

Per-domain configuration (recommended):

# Replace your-domain.com with your GitRepublic server domain
git config --global credential.https://your-domain.com.helper '!node /absolute/path/to/gitrepublic-web/scripts/git-credential-nostr.js'

Localhost configuration (for local development):

If you're running GitRepublic on localhost, configure it like this:

# For HTTP (http://localhost:5173)
git config --global credential.http://localhost.helper '!node /absolute/path/to/gitrepublic-web/scripts/git-credential-nostr.js'

# For HTTPS (https://localhost:5173) - if using SSL locally
git config --global credential.https://localhost.helper '!node /absolute/path/to/gitrepublic-web/scripts/git-credential-nostr.js'

# For a specific port (e.g., http://localhost:5173)
git config --global credential.http://localhost:5173.helper '!node /absolute/path/to/gitrepublic-web/scripts/git-credential-nostr.js'

Note: Git's credential helper matching is based on the hostname, so localhost will match localhost:5173 automatically. If you need to match a specific port, include it in the configuration.

Per-repository configuration:

cd /path/to/your/repo
git config credential.helper '!node /absolute/path/to/gitrepublic-web/scripts/git-credential-nostr.js'

Usage

Once configured, git will automatically use the credential helper for authentication:

Clone a private repository

# Remote server
git clone https://your-domain.com/npub1abc123.../my-repo.git

# Localhost (local development)
# The git HTTP backend is at /api/git/
git clone http://localhost:5173/api/git/npub1abc123.../my-repo.git

The credential helper will automatically generate a NIP-98 auth token using your NOSTRGIT_SECRET_KEY.

Localhost Setup Example

Here's a complete example for setting up the credential helper with a local GitRepublic instance:

1. Start your local GitRepublic server

cd /path/to/gitrepublic-web
npm run dev
# Server runs on http://localhost:5173

2. Set your NOSTRGIT_SECRET_KEY

export NOSTRGIT_SECRET_KEY="nsec1..."

3. Configure git for localhost

# Configure for localhost (any port)
git config --global credential.http://localhost.helper '!node /absolute/path/to/gitrepublic-web/scripts/git-credential-nostr.js'

# Or for a specific port (e.g., 5173)
git config --global credential.http://localhost:5173.helper '!node /absolute/path/to/gitrepublic-web/scripts/git-credential-nostr.js'

4. Clone a repository

# Replace npub1abc123... with the actual npub and my-repo with your repo name
git clone http://localhost:5173/api/git/npub1abc123.../my-repo.git

5. Add remote and push

cd my-repo

# If you need to add the remote manually
git remote add gitrepublic-web http://localhost:5173/api/git/npub1abc123.../my-repo.git

# Make some changes and push
git add .
git commit -m "Initial commit"
git push -u gitrepublic-web main

Note: The git HTTP backend endpoint is /api/git/, so the full URL format is:

http://localhost:5173/api/git/{npub}/{repo-name}.git

Push changes

git push gitrepublic-web main

The credential helper will generate the appropriate NIP-98 auth token for push operations.

Fetch/Pull

git fetch gitrepublic-web
git pull gitrepublic-web main

How It Works

When git needs credentials, it calls the credential helper with the repository URL
The helper reads your NOSTRGIT_SECRET_KEY environment variable
It creates a NIP-98 authentication event signed with your private key for the specific URL and HTTP method
The signed event is base64-encoded and returned as username=nostr and password=<base64-event>
Git converts this to Authorization: Basic <base64(username:password)> header
The GitRepublic server detects Basic auth with username "nostr" and converts it to Authorization: Nostr <base64-event> format
The server verifies the NIP-98 auth event (signature, URL, method, timestamp) and grants access if valid

Important: The credential helper generates fresh credentials for each request because NIP-98 requires per-request authentication tokens. The URL and HTTP method are part of the signed event, so credentials cannot be reused.

Troubleshooting

Error: NOSTRGIT_SECRET_KEY environment variable is not set

Make sure you've exported the NOSTRGIT_SECRET_KEY variable:

export NOSTRGIT_SECRET_KEY="nsec1..."

Note: The script also supports NOSTR_PRIVATE_KEY and NSEC for backward compatibility, but NOSTRGIT_SECRET_KEY is the preferred name.

Error: Invalid nsec format

Ensure your nsec starts with nsec1 (bech32 encoded)
Or use a 64-character hex private key
Check that the key is not corrupted or truncated

Authentication fails

Verify your private key matches the public key that has access to the repository
Check that the repository URL is correct
Ensure your key has maintainer permissions for push operations

If you see a login dialog when pushing, git isn't calling the credential helper for the POST request. This usually happens because:

Credential helper not configured correctly:

# Check your credential helper configuration
git config --global --get-regexp credential.helper

# Make sure the GitRepublic helper is configured for your domain
git config --global credential.http://localhost:5173.helper '!node /path/to/gitrepublic-web/scripts/git-credential-nostr.js'

Other credential helpers interfering: Git might be using cached credentials from another helper. Make sure the GitRepublic helper is listed FIRST:

# Remove all credential helpers
git config --global --unset-all credential.helper

# Add only the GitRepublic helper
git config --global credential.http://localhost:5173.helper '!node /path/to/gitrepublic-web/scripts/git-credential-nostr.js'

NOSTRGIT_SECRET_KEY not set: Make sure the environment variable is set in the shell where git runs:
```
export NOSTRGIT_SECRET_KEY="nsec1..."
```
Wrong private key: Ensure your NOSTRGIT_SECRET_KEY matches the repository owner or you have maintainer permissions for the repository you're pushing to.
Authorization failure (403): If authentication succeeds but push fails with 403, check:
- Your pubkey matches the repository owner, OR
- You have maintainer permissions for the repository
- Branch protection rules allow your push

Security Best Practices

Never commit your NOSTRGIT_SECRET_KEY to version control
- Add NOSTRGIT_SECRET_KEY to your .gitignore if you store it in a file
- Use environment variables instead of hardcoding
- Important: This is YOUR user key for client-side operations
Use per-domain configuration
- This limits the credential helper to only GitRepublic domains
- Prevents accidental credential leaks to other services
Protect your private key
- Use file permissions: chmod 600 ~/.nostr-key (if storing in a file)
- Consider using a key management service for production
Rotate keys if compromised
- If your NOSTR_PRIVATE_KEY is ever exposed, generate a new key pair
- Update repository maintainer lists with your new public key

Alternative: Manual Authentication

If you prefer not to use the credential helper, you can manually generate NIP-98 auth tokens, but this is not recommended for regular use as it's cumbersome.

9.4 KiB Raw Blame History