npm package: @sekyuriti/trace
Description: File origin verification - register and trace files with SEKYURITI
Author: SEKYURITI
Latest version: 0.1.0

# @sekyuriti/trace

File origin verification. Register files and let anyone trace them back to you.

## Quick Start

```bash
npx @sekyuriti/trace login
```

This will:
1. Open browser for authentication
2. Let you select your project
3. Save your API key locally

## CLI Commands

```bash
trace login              # Authenticate with SEKYURITI
trace logout             # Sign out
trace register <file>    # Register a file for tracing
trace check <file>       # Trace a file's origin
trace revoke <id>        # Revoke a file registration
trace status             # Show account info
trace help               # Show help
```

## Examples

### Register a file
```bash
trace register contract.pdf
# Output:
# ✓ File registered
# Trace ID: TRC.A1B2.C3D4
# URL: https://sekyuriti.build/trace?id=TRC.A1B2.C3D4
```

### Check a file's origin
```bash
trace check download.exe
# Output:
# ✓ TRACED
# Origin: ACME Corp
# Registered: 2026-01-18
```

### Revoke a registration
```bash
trace revoke TRC.A1B2.C3D4
```

## Programmatic Usage

```typescript
import { createTraceClient } from "@sekyuriti/trace";

const trace = createTraceClient({
  apiKey: process.env.TRACE_API_KEY,
});

// Register a file
const result = await trace.register({
  filePath: "./contract.pdf",
  fileName: "contract.pdf",
  description: "Service Agreement v2",
});

console.log(result.trace_id); // TRC.A1B2.C3D4
console.log(result.trace_url); // https://sekyuriti.build/trace?id=TRC.A1B2.C3D4

// Trace a file
const traceResult = await trace.trace({
  filePath: "./download.exe",
});

if (traceResult.result === "traced") {
  console.log(`Origin: ${traceResult.file.issuer_name}`);
}

// Revoke a registration
await trace.revoke("TRC.A1B2.C3D4", "File replaced with new version");
```

## API Reference

### `createTraceClient(config)`

Create a TRACE client.

```typescript
const trace = createTraceClient({
  apiKey: string, // Your TRACE API key
});
```

### `trace.register(options)`

Register a file for tracing.

```typescript
await trace.register({
  filePath?: string,      // Path to file (will be hashed)
  fileHash?: string,      // Or provide hash directly
  fileName: string,       // Required
  fileSize?: number,
  description?: string,
  metadata?: object,
});
```

### `trace.trace(options)`

Trace a file's origin.

```typescript
await trace.trace({
  filePath?: string,   // Path to file
  fileHash?: string,   // Or hash directly
  traceId?: string,    // Or trace ID
});
```

### `trace.revoke(traceId, reason?)`

Revoke a file registration.

```typescript
await trace.revoke("TRC.A1B2.C3D4", "Optional reason");
```

### `trace.hashFile(filePath)`

Hash a file using SHA-256.

```typescript
const hash = await trace.hashFile("./file.pdf");
```

## How It Works

1. **Register**: When you register a file, we store its SHA-256 hash with your identity
2. **Trace**: Anyone can drop a file on sekyuriti.build/trace to check its origin
3. **Verify**: If the hash matches, they see who registered it and when

Nothing is uploaded during tracing - files are hashed locally.

## Documentation

https://sekyuriti.build/docs/trace

## License

MIT