Authentication & Security

Every request uses JWT tokens you sign and control. Generate short-lived tokens for CI/CD, long-lived tokens for development, and manage permissions with fine-grained scopes—no third-party authentication required.

All access to Code Storage requires JWT tokens signed by your organization. Each token:

• Grants access to a single repository
• Contains explicit permission scopes
• Has a configurable time-to-live (TTL)
• Is customer-signed for full control

The SDK helps simplify and automate the management of these tokens.

Token structure

{
  "iss": "your-org", // Your organization identifier
  "sub": "ci-pipeline-prod", // Agent identity (for logging)
  "repo": "team/project-alpha", // Repository access
  "scopes": ["git:read", "git:write"], // Permissions
  "iat": 1723453189, // Issued at (Unix timestamp)
  "exp": 1723456789 // Expiration (Unix timestamp)
}

SDK note: the client normalizes Git status codes in state to descriptive values and provides the original status under rawState alongside camelCase property names.

JWT headers must include:

{
  "alg": "ES256", // Algorithm (ECDSA with P-256 curve)
  "typ": "JWT", // Type
  "kid": "key-2024-01" // Key ID for rotation
}

Permission scopes

Scope	Description	Operations
git:read	Read repository contents	clone, fetch, pull
git:write	Modify repository	push (includes read)
repo:write	Create repositories	POST /api/v1/repos
git:write	Sync from upstream	POST /api/v1/repos/pull-upstream

Key management

Public keys for JWT verification are managed through the Pierre Admin Panel. The kid (Key ID) header enables zero-downtime key rotation—register new keys before retiring old ones.

Manual JWT generation

For advanced scenarios—such as integrating with custom Git tooling or provisioning tokens outside the SDK clients—you can generate JWTs directly with the generateJwt / generate_jwt helpers. They accept your PEM-encoded private key, repository identifier, and desired scopes, then return a ready to use token:

TypeScript

import { promises as fs } from 'node:fs';
import { generateJwt } from '@pierre/storage';

// Load your private key from disk (PKCS8 PEM)
const keyPem = await fs.readFile('path/to/key.pem', 'utf8');

const token = generateJwt({
  keyPem,
  issuer: 'your-name', // e.g., 'v0'
  repoId: 'your-repo-id',
  scopes: ['git:write', 'git:read'], // optional, defaults to read/write
  ttl: 3600, // optional, defaults to 1 year (in seconds)
});

const gitUrl = `https://t:${token}@your-name.code.storage/your-repo-id.git`;
console.log(`git clone ${gitUrl}`);

Parameters

• keyPem / key_pem (required): Private key in PKCS8 PEM format. RSA, EC (P-256), and EdDSA keys are supported.
• issuer (required): Customer identifier (for example your-name in HTTPS remotes).
• repoId / repo_id (required): Repository ID the token will access.
• scopes (optional): Explicit permissions. Defaults to ["git:write", "git:read"]. Available scopes: git:read, git:write, repo:write.
• ttl (optional): Token lifetime in seconds. Defaults to 31536000 (1 year).

The helper auto-detects the key type and signs with RS256, ES256, or EdDSA as appropriate.