npm package: @longarc/verify
Description: Verify mdash attestation credentials. Zero deps. One function.
Author: Long Arc Studios
Latest version: 0.1.1

# @longarc/verify

Verify mdash attestation credentials. Zero deps. One function.

## Install

```bash
npm install @longarc/verify
```

## Quick Start

```typescript
import { verify } from '@longarc/verify';

const result = verify(credential);
if (result.valid) {
  console.log(`Verified: tier=${result.tier}, scope=${result.scope}`);
} else {
  console.log(`Rejected: ${result.reason}`);
}
```

## API

### `verify(credential, options?): VerificationResult`

Full trust assessment. Checks structure, timestamps, and Ed25519 signature.

```typescript
const result = verify(credential);
// { valid: true, tier: 'L2', scope: ['read', 'write'], issuer: 'a1b2c3d4e5f6...' }

const result = verify(expiredCredential);
// { valid: false, tier: 'L2', scope: ['read'], issuer: '...', reason: 'expired' }
```

### `isAttested(credential, options?): boolean`

Boolean gate. Returns `true` if the credential is valid and not expired.

```typescript
if (isAttested(credential)) {
  // Proceed with trusted operation
}
```

### `extractTier(credential): 'L1' | 'L2' | 'L3' | null`

Fast tier extraction without full verification. Returns `null` for structurally invalid credentials.

```typescript
const tier = extractTier(credential);
// 'L1' | 'L2' | 'L3' | null
```

### `extractScope(credential): string[] | null`

Extract scope array without full verification.

```typescript
const scope = extractScope(credential);
// ['read', 'write'] | null
```

### `createVerifier(options): Verifier`

Factory for pre-configured verifier with pinned keys.

```typescript
import { createVerifier } from '@longarc/verify';

const verifier = createVerifier({
  pinnedKeys: ['a1b2c3...'], // Only accept credentials from these issuers
  strictIssuedAt: true,       // Reject future-dated credentials
});

const result = verifier.verify(credential);
```

## Integration Examples

### MCP Middleware

```typescript
import { isAttested } from '@longarc/verify';

function mdashGate(credential) {
  if (!isAttested(credential)) throw new Error('Unattested agent');
}
```

### LangChain Callback

```typescript
import { verify } from '@longarc/verify';

const handler = { handleToolStart(tool, input, meta) {
  const result = verify(meta.credential);
  if (!result.valid) throw new Error(`Rejected: ${result.reason}`);
}};
```

### Express Middleware

```typescript
import { verify } from '@longarc/verify';

app.use('/api/agent', (req, res, next) => {
  const result = verify(req.headers['x-mdash-credential']);
  if (!result.valid) return res.status(403).json({ error: result.reason });
  req.attestation = result;
  next();
});
```

## Credential Format

```typescript
interface Credential {
  payload: {
    agentId: string;
    tier: 'L1' | 'L2' | 'L3';
    scope: string[];
    services?: string[];
    memoryHash?: string;
  };
  signature: string;   // Ed25519 signature (hex)
  publicKey: string;    // Ed25519 public key (hex)
  issuedAt: string;     // ISO-8601
  expiresAt: string;    // ISO-8601
}
```

## Security Model

- **Offline**: No network calls, no external dependencies
- **Deterministic**: Payload serialized with sorted keys before verification
- **Ed25519**: Industry-standard signature scheme via Node.js crypto
- **Distillation-resistant**: Signature covers all payload fields — tier, scope, services, memory state. Altering any field invalidates the signature.

This package verifies credentials. It does not issue them (that's the Depot) or enforce runtime constraints (that's the Warden).

## License

Apache-2.0 — Long Arc Studios