7.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

Global configuration (for all GitRepublic repositories):

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

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 (with fallbacks for backward compatibility)
It creates a NIP-98 authentication event signed with your private key
The signed event is base64-encoded and returned as the "password"
Git sends this in the Authorization: Nostr <base64-event> header
The GitRepublic server verifies the NIP-98 auth event and grants access

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

Push operations fail

Push operations require POST authentication. The credential helper automatically detects push operations (when the path contains git-receive-pack) and generates a POST auth event. If you still have issues:

Verify you have maintainer permissions for the repository
Check that branch protection rules allow your push
Ensure your NOSTRGIT_SECRET_KEY is correctly set

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.

7.4 KiB Raw Blame History