Par Noir Documentation

Welcome to the Par Noir documentation. Par Noir is an open-source protocol for sovereign identity, building a more secure and equitable foundation for the internet.

Quick Start

Get started with Par Noir in minutes. This guide will walk you through the basic setup and authentication flow.

npm install @par-noir/identity-sdk

import { createIdentitySDK } from '@par-noir/identity-sdk';

const sdk = createIdentitySDK({
  clientId: 'your-client-id',
  redirectUri: 'https://your-app.com/callback',
  scope: 'openid profile email'
});

// Initialize authentication
sdk.authenticate();

// Handle the OAuth callback
sdk.handleCallback().then(user => {
  console.log('Authenticated user:', user);
  // User is now authenticated with their sovereign identity
});

Authentication

Par Noir uses OAuth 2.0 with sovereign identity for secure authentication. Users authenticate with their personal identity file (.did) and passcode.

OAuth 2.0 Flow

1. Authorization Request: Redirect user to Par Noir with your app's credentials
2. Identity Verification: User uploads their .did file and enters passcode
3. Authorization Grant: User grants permission to your application
4. Token Exchange: Exchange authorization code for access token
5. API Access: Use access token to call protected endpoints

Base URL

https://identity-protocol.com/api

Authentication Header

Authorization: Bearer <access_token>

OAuth Endpoints

1. Authorization Endpoint

Endpoint: GET /oauth/authorize

Initiates the OAuth 2.0 authorization code flow.

Parameters:

• response_type (required): Must be code
• client_id (required): Your application's client ID
• redirect_uri (required): Your application's callback URL
• scope (optional): Space-separated list of requested scopes
• state (optional): Random string for CSRF protection
• nonce (optional): Random string for replay protection

GET /oauth/authorize?response_type=code&client_id=your-client-id&redirect_uri=https://your-app.com/callback&scope=openid%20profile%20email&state=random-string

2. Token Endpoint

Endpoint: POST /oauth/token

Exchanges authorization code for access token.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=authorization_code&client_id=your-client-id&client_secret=your-client-secret&redirect_uri=https://your-app.com/callback

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email",
  "state": "random-string"
}

User Endpoints

User Info Endpoint

Endpoint: GET /oauth/userinfo

Returns user information based on the access token.

GET /oauth/userinfo
Authorization: Bearer your-access-token

{
  "sub": "user-id",
  "name": "John Doe",
  "email": "john@example.com",
  "username": "johndoe",
  "created_at": "2024-01-01T00:00:00Z",
  "verified": true
}

JavaScript SDK

The Par Noir JavaScript SDK provides a simple interface for integrating sovereign identity authentication into your web applications.

Installation

npm install @par-noir/identity-sdk

Basic Usage

import { createIdentitySDK } from '@par-noir/identity-sdk';

const sdk = createIdentitySDK({
  clientId: 'your-client-id',
  redirectUri: 'https://your-app.com/callback',
  scope: 'openid profile email'
});

Authentication Flow

// 1. Start authentication
sdk.authenticate();

// 2. Handle callback (in your callback page)
sdk.handleCallback().then(user => {
  console.log('User authenticated:', user);
  
  // 3. Get user info
  return sdk.getUserInfo();
}).then(userInfo => {
  console.log('User info:', userInfo);
}).catch(error => {
  console.error('Authentication failed:', error);
});

React Hooks

Par Noir provides React hooks for easy integration with React applications.

import { useIdentitySDK } from '@par-noir/identity-sdk/react';

function App() {
  const { user, isAuthenticated, authenticate, logout } = useIdentitySDK({
    clientId: 'your-client-id',
    redirectUri: 'https://your-app.com/callback'
  });

  if (isAuthenticated) {
    return (
      

        
Welcome, {user.name}!
        Logout
      
    );
  }

  return (
    

      
Welcome to Par Noir
      Login with Par Noir
    
  );
}

Age Verification Tutorial

Learn how to implement age verification using Par Noir's zero-knowledge proofs without storing personal data.

Overview

This tutorial shows how to verify a user's age without storing their actual birth date, using cryptographic proofs.

import { createAgeVerification } from '@par-noir/identity-sdk';

const ageVerifier = createAgeVerification({
  minimumAge: 18,
  clientId: 'your-client-id'
});

// Verify age without revealing birth date
ageVerifier.verifyAge(userProof).then(isValid => {
  if (isValid) {
    console.log('User is 18 or older');
  } else {
    console.log('User is under 18');
  }
});

Zero-Knowledge Proofs

Par Noir uses zero-knowledge proofs to enable privacy-preserving authentication and verification.

What are Zero-Knowledge Proofs?

Zero-knowledge proofs allow you to prove that you know something without revealing what you know. For example, you can prove you're over 18 without revealing your exact age.

Types of Proofs

• Age Verification: Prove age without revealing birth date
• Location Verification: Prove location without revealing exact coordinates
• Identity Verification: Prove identity without revealing personal details

import { createProof } from '@par-noir/identity-sdk';

// Create a proof that user is over 18
const proof = await createProof({
  type: 'age',
  value: userAge,
  constraint: '>= 18'
});

// The proof can be verified without revealing the actual age
const isValid = await verifyProof(proof);
console.log('Proof is valid:', isValid);

Security Best Practices

Follow these security guidelines to ensure your Par Noir integration is secure.

Client Security

• Always use HTTPS in production
• Store client secrets securely (server-side only)
• Validate redirect URIs to prevent open redirects
• Use state parameters for CSRF protection

Token Security

• Store access tokens securely
• Never expose tokens in client-side code
• Implement proper token refresh logic
• Validate token expiration

User Data Protection

• Only request necessary scopes
• Implement proper data retention policies
• Use zero-knowledge proofs when possible
• Encrypt sensitive data at rest

Code Examples

Explore working examples of Par Noir integration in different frameworks and languages.

Frequently Asked Questions

Community

Join the Par Noir community to get help, share ideas, and contribute to the project.