@certivu/sdk 1.0.0

package/README.md

@@ -0,0 +1,180 @@
+# @certivu/sdk
+
+Official SDK for [Certivu](https://certivu.ai) — quantum-resistant provenance for AI-generated content.
+
+Certivu signs AI-generated content with ML-DSA (NIST FIPS 204) cryptographic signatures and invisible frequency-domain watermarks. Anyone can verify signed content without an account.
+
+## Install
+
+```bash
+npm install @certivu/sdk
+# or
+bun add @certivu/sdk
+```
+
+Requires Node.js 18+ (uses built-in `fetch`, `Blob`, `crypto`).
+
+## Quickstart
+
+```typescript
+import { CertivuClient } from '@certivu/sdk'
+
+const certivu = new CertivuClient({
+  apiKey: 'ctv_key_abc123',
+  generatorId: 'gen_xyz',
+  privateKey: '<base64-encoded ML-DSA private key>',
+})
+
+// Sign AI-generated content
+const { token } = await certivu.sign({
+  content: imageBuffer,   // Buffer, Uint8Array, or string
+  model: 'stable-diffusion-xl',
+})
+// Embed `token` in XMP metadata or pass alongside content for verification
+
+// Verify — token optional, extracted automatically from XMP or watermark
+const result = await certivu.verify({ content: imageBuffer })
+
+if (result.authentic && result.confidence === 'high') {
+  console.log('Verified:', result.provenance?.org, result.provenance?.signed_at)
+}
+```
+
+Get your API key and generator credentials at [dashboard.certivu.ai](https://dashboard.certivu.ai).
+
+---
+
+## API Reference
+
+### `new CertivuClient(config)`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `apiKey` | `string` | Yes | API key from the dashboard (`ctv_key_...`) |
+| `generatorId` | `string` | No | Default generator ID for sign calls |
+| `privateKey` | `string` | No | Base64-encoded ML-DSA private key for sign calls |
+| `baseUrl` | `string` | No | Override API base URL (default: `https://api.certivu.ai`) |
+
+---
+
+### `certivu.sign(input)`
+
+Signs AI-generated content and stores a provenance record.
+
+```typescript
+const { token, record_id } = await certivu.sign({
+  content: imageBuffer,            // Uint8Array | string
+  model: 'stable-diffusion-xl',   // model identifier
+  generatorId: 'gen_xyz',         // overrides config.generatorId
+  privateKey: '...',              // overrides config.privateKey
+})
+```
+
+Returns `{ token: string, record_id: string }`. Embed the `token` in XMP metadata or store it alongside the content.
+
+---
+
+### `certivu.verify(input)`
+
+Verifies content authenticity. Token is optional — Certivu extracts it automatically from XMP metadata or the frequency-domain watermark.
+
+```typescript
+const result = await certivu.verify({
+  content: imageBuffer,   // Uint8Array | string
+  token: 'ctv_...',      // optional — skip to let Certivu extract it
+})
+```
+
+**Response shape:**
+
+```typescript
+{
+  authentic: boolean,
+  tampered: boolean,
+  confidence: 'high' | 'medium' | 'low' | 'none',
+  token_source: 'provided' | 'xmp' | 'watermark',
+  signals: {
+    watermark_found: boolean,
+    record_found: boolean,
+    signature_valid: boolean,
+  },
+  provenance: {
+    org: string,
+    model: string,
+    signed_at: string,
+  } | null,
+  reason?: string,   // present when authentic: false
+}
+```
+
+**Confidence levels:**
+
+| Confidence | Meaning |
+|---|---|
+| `high` | Watermark + record + signature all valid |
+| `medium` | Record + signature valid, no watermark (e.g. re-uploaded without it) |
+| `low` | Partial signals — something is off |
+| `none` | No provenance data found — no claim either way |
+
+> Absence of provenance does **not** imply human origin. Certivu verifies declared provenance; it does not detect all AI content.
+
+---
+
+### `certivu.verifyBatch(items)`
+
+Verify up to 50 items in a single request.
+
+```typescript
+const { results } = await certivu.verifyBatch([
+  { content: image1, token: token1 },
+  { content: image2 },             // token optional per item
+])
+
+for (const result of results) {
+  console.log(result.authentic, result.confidence)
+}
+```
+
+---
+
+### `certivu.getAuditLog(options?)`
+
+Fetch a paginated audit log of sign, verify, and key events for your org.
+
+```typescript
+const { events, total, page, limit } = await certivu.getAuditLog({
+  page: 1,
+  limit: 50,
+})
+```
+
+---
+
+## Error handling
+
+All methods throw an `Error` with a descriptive message on API or network failure.
+
+```typescript
+try {
+  await certivu.sign({ content, model: 'sdxl' })
+} catch (e) {
+  if (e instanceof Error) {
+    console.error(e.message)  // e.g. "signature_limit_reached"
+  }
+}
+```
+
+Common error codes:
+
+| Code | Meaning |
+|---|---|
+| `signature_limit_reached` | Free plan 500/mo limit hit — upgrade at certivu.ai/pricing |
+| `generator_not_found` | `generatorId` doesn't exist or belongs to another org |
+| `generator_revoked` | Generator has been revoked — all its signatures are invalid |
+| `invalid_api_key` | API key is missing, malformed, or revoked |
+
+---
+
+## Docs
+
+Full documentation at [docs.certivu.ai](https://docs.certivu.ai).

package/dist/client.d.ts

@@ -0,0 +1,14 @@
+import type { VerificationResult } from "@certivu/types";
+import type { AuditOptions, AuditPage, BatchItem, BatchVerifyResponse, ClientConfig, SignInput, SignResponse, VerifyInput } from "./types/options";
+export declare class CertivuClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly generatorId;
+    private readonly privateKey;
+    constructor(config: ClientConfig);
+    sign(input: SignInput): Promise<SignResponse>;
+    verify(input: VerifyInput): Promise<VerificationResult>;
+    verifyBatch(items: BatchItem[]): Promise<BatchVerifyResponse>;
+    getAuditLog(options?: AuditOptions): Promise<AuditPage>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAIzD,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,SAAS,EACT,mBAAmB,EACnB,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,WAAW,EACZ,MAAM,iBAAiB,CAAC;AAEzB,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;gBAEpC,MAAM,EAAE,YAAY;IAO1B,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC;IAU7C,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIvD,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI7D,WAAW,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC;CAG9D"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { CertivuClient } from "./client";
+export type { AuditOptions, AuditPage, BatchItem, BatchVerifyResponse, ClientConfig, SignInput, SignResponse, VerifyInput, } from "./types/options";
+export type { AuditEvent, VerificationResult } from "@certivu/types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,YAAY,EACV,YAAY,EACZ,SAAS,EACT,SAAS,EACT,mBAAmB,EACnB,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}