@prampta/sdk 0.3.2 → 0.7.0

package/README.md

@@ -1,284 +1,366 @@
-# @prampta/sdk
+# PRAMPTA TypeScript SDK
 
-Official Node.js SDK for the PRAMPTA API — create, search, and manage AI prompts with automatic retry logic and TypeScript support.
-
-## Features
-
-- **TypeScript-first** with full type definitions
-- **Automatic retries** with exponential backoff
-- **Request cancellation** via AbortSignal
-- **Rate limit handling** with intelligent retry
-- **Zero dependencies** (uses native fetch)
+Pre-generation authorization for AI content. Verifies operator Ed25519 signatures on decisions — not a blind HTTP wrapper.
 
 ## Installation
 
 ```bash
 npm install @prampta/sdk
-# or
-pnpm add @prampta/sdk
-# or
-yarn add @prampta/sdk
 ```
 
+0.7.0 requires Node **20.19.x or newer 20.x, or 22.12+**. Earlier runtime
+support is not claimed: CommonJS loads the ESM-only crypto dependency through
+[`require(esm)`](https://nodejs.org/en/blog/release/v20.19.0). Local ESM/CommonJS
+smoke tests run on Node 22.20; a wider runtime/browser matrix is still a release gate.
+
+This README describes SDK 0.7.0.
+In older 0.4.0, `assertAllowed` throws on
+personal-use `not_blocked` and `PramptaReporter` is unavailable. Use `verify()`
+and inspect `disposition` when supporting older installations;
+`not_blocked` is not a licence in any version.
+
+## Authentication
+
+`token` is your **runtime credential** — a `ProviderCredential` `exchange_secret`,
+issued the moment you complete provider onboarding (inline in the
+`verify-email` response for sandbox, `verify-domain/confirm` for production).
+The `prampta_connection_token` returned by the Connect AI code exchange is not
+accepted by production for runtime calls — use the `exchange_secret`, and pass
+the user's `prampta_licensee_id` as `licenseeId`. See
+[docs/PRAMPTA-Provider-Connect-Guide-2026-08.md](../../docs/PRAMPTA-Provider-Connect-Guide-2026-08.md)
+in the main repo for the full onboarding flow.
+
+There used to be a second way in — a shared **pair token** — kept alive only
+for deployments still running in `PILOT_MODE` while a provider migrates. A
+production PRAMPTA deployment running the v1.0.0-default trust posture
+refuses it with `PG_NO_PAIR`. Don't build a new integration against it; it
+exists solely so an already-connected provider keeps working mid-migration.
+
 ## Quick Start
 
 ```typescript
-import { Prampta } from '@prampta/sdk';
-
-const prampta = new Prampta({
-  apiKey: 'pk_xxxx-xx-xx-xx-xxxxxx', // Get at prampta.com/profile
+import { Prampta } from "@prampta/sdk";
+
+const pg = new Prampta({
+  baseUrl: "https://api2.prampta.com",
+  providerId: "my-ai-service",
+  licenseeId: "lic-sandbox", // synthetic fixture only
+  token: process.env.PRAMPTA_TOKEN, // sandbox exchange_secret; server-side only
+  operatorPublicKeyHex: process.env.PRAMPTA_OPERATOR_PUBLIC_KEY, // obtained independently
 });
 
-// Create a prompt
-const result = await prampta.create({
-  content: 'Write a TypeScript function that validates email addresses...',
-  title: 'Email Validator',
+// Option 1: Assert — throws if denied. This sandbox fixture has a research licence.
+await pg.assertAllowed("sbx-allowed", {
+  prompt: "A sandbox portrait",
+  modality: "image",
+  model: "your-model",
+  intendedUse: { useCase: "research" },
 });
-console.log('Created:', result.ppCode); // PP-3YGBM5V0HN-4
 
-// Decode a prompt
-const prompt = await prampta.decode('PP-3YGBM5V0HN-4');
-console.log(prompt.content);
-
-// Search prompts
-const { prompts } = await prampta.search({
-  query: 'typescript',
-  category: 'development',
-  limit: 10,
+// Option 2: Verify — returns decision object
+const result = await pg.verify("sbx-allowed", {
+  prompt: "A sandbox portrait",
+  modality: "image",
+  model: "your-model",
+  intendedUse: { useCase: "research" },
 });
-```
 
-## API Reference
-
-### Constructor
-
-```typescript
-new Prampta(config: PramptaConfig)
+if (result.allowed) {
+  generate({ obligations: result.obligations });
+} else {
+  console.log(`Denied: ${result.reason}`);
+}
 ```
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `apiKey` | `string` | (required) | Your API key (starts with `pk_`) |
-| `baseUrl` | `string` | `https://prampta.com` | API base URL |
-| `timeoutMs` | `number` | `30000` | Request timeout in ms |
-| `maxRetries` | `number` | `3` | Max retry attempts |
-
-### Methods
+For real users, replace `lic-sandbox` with the connected user's
+`prampta_licensee_id` and use a subject and licence that actually cover the
+declared purpose. For unlicensed personal use, omit `licenseeId`, declare
+`useCase: "personal"`, call `verify()` and handle `not_blocked` separately;
+it grants no rights and has no licence receipt. After an `allow` generation,
+file the receipt described in the [Connect Step 2 guide](https://prampta.com/get-started.md).
 
-#### `decode(code, options?)`
+## Strict license-backed authorization (0.7.0)
 
-Get the full prompt content by PP code.
+`assertAllowed` preserves reporting-only personal use. `assertLicensed` is
+the explicit license-backed path: signature verification and pinned operator
+keys are mandatory, as is your generation id. It rejects `not_blocked`,
+`review`, `deny`, and an internal `allow` without a license, even in monitor
+mode. This verifies a decision, not rights-holder authority or output compliance.
 
 ```typescript
-const prompt = await prampta.decode('PP-3YGBM5V0HN-4');
-// Returns: Prompt with content, media, metadata
+const decision = await pg.assertLicensed(subjectCode, {
+  promptHash, generationId: jobId, modality: "video", model: modelName,
+  intendedUse: { useCase: "commercial", rights: ["output_generation"] },
+});
+// Apply the decision's obligations, generate, then submit a receipt.
 ```
 
-#### `lookup(code, options?)`
-
-Get prompt metadata without content (increments usage counter).
+## Check answers against PRE-GEN (recommended)
 
 ```typescript
-const metadata = await prampta.lookup('PP-3YGBM5V0HN-4');
-// Returns: PromptMetadata (no content field)
-```
+import { Prampta, loadPregenDirectory } from "@prampta/sdk";
 
-#### `search(searchOptions?, requestOptions?)`
+const pregenDirectory = await loadPregenDirectory({ previous: saved }); // steward key built in
+saved = pregenDirectory.toJSON();                                       // keep it for next start
 
-Search the public prompt library.
-
-```typescript
-const result = await prampta.search({
-  query: 'react hooks',
-  category: 'development', // development, design, marketing, data, writing, business
-  limit: 20,
-  page: 1,
-});
-// Returns: { prompts, total, page, totalPages }
+const registry = new Prampta({ baseUrl: "https://api2.prampta.com", providerId, token, licenseeId,
+  pregenDirectory });
 ```
 
-#### `create(options, requestOptions?)`
+With `pregenDirectory` the SDK refuses to send a PG code to a registry that
+does not own its namespace, and on every `allow` runs `checkDecision` from
+[`@pregen/verify`](https://www.npmjs.com/package/@pregen/verify): the signing
+key must be one the signed PRE-GEN directory lists for the license's
+namespace, and the origin registry's keys are pinned in that library, so a
+stolen steward key cannot add its own. The directory also refuses an older or
+shrunk copy of itself when you pass the previous one back.
+
+For CI without a secret, `createSimulator()` from `@pregen/verify` 0.4.0 is an
+offline sandbox registry: pass `baseUrl: sim.baseUrl`, `operatorPublicKeyHex:
+sim.operatorPublicKeyHex`, `pregenDirectory: sim.directory` and use `sim.fetch`.
 
-Create a new prompt.
+## Optional namespace trust with your own root (0.7.0)
 
 ```typescript
-const result = await prampta.create({
-  content: 'Your prompt content here (10-50,000 chars)',
-  title: 'Optional title',
-  media: {
-    'img1': 'data:image/png;base64,...', // Optional media attachments
-  },
+import { TrustedRegistryDirectory } from "@prampta/sdk";
+const directory = await TrustedRegistryDirectory.verify(signedDirectory, {
+  stewardPublicKeyHex: independentlyObtainedStewardKey,
+  previousSnapshot: savedState, // { sequence, hash }, loaded from durable storage
+});
+// Atomically persist { sequence: directory.sequence, hash: directory.snapshotHash }
+// after acceptance, without letting concurrent updates overwrite newer state.
+const registry = new Prampta({
+  baseUrl: registryApi, providerId, token: serverSideCredential, licenseeId,
+  operatorPublicKeyHex: independentlyObtainedOperatorKey,
+  registryDirectory: directory,
 });
-// Returns: { ppCode, title, category, tags }
 ```
 
-#### `myPrompts(options?)`
-
-List your own prompts.
+This opt-in validates the signed `pregen.registries.v2` directory, requires
+HTTPS registry URLs, rejects ambiguous shared signing keys/endpoints, checks
+the target namespace before sending credentials, and checks a returned
+license's issuer. Origin and prefixed registries get the same checks. Local
+subject ids remain supported at an explicitly listed registry endpoint.
+Authenticated calls do not follow redirects. No automatic multi-registry
+credential sharing or onboarding is provided.
+Persisted `previousSnapshot` detects rollback and signed different-content
+snapshots at the same sequence. `minSequence` is also available for a sequence
+floor alone. Storage and concurrent update serialization belong to the host.
+
+The public steward key is still pending: do not obtain a trust anchor from
+the directory itself or invent a production key. An authenticated directory
+snapshot does not prove freshness, key non-revocation or rights-holder consent;
+`minSequence` alone does not prevent stale first-boot snapshots. Full live
+federation needs the separately specified trust-management work.
+
+`verifyLicenseSignatures()` checks the subject signature and the operator
+countersignature over body + subject signature + license id offline. Obtain
+keys independently, then verify namespace, authority, status and scope separately.
+Two valid signatures under managed custody are not two independent consents.
+
+Security fixes also reject empty request bindings, mismatched generation ids,
+unsupported schemas, contradictory outcomes, missing/invalid expiry and
+non-integer or unsafe signed JSON numbers. Optional advisory fields remain
+signed. An asserted end user cannot silently receive an unbound `allow`.
+Pass a known `providerIdentityLinkId` for exact link matching; resolution of
+`providerUserId` alone still relies on the registry's user-to-link mapping.
+Existing valid signed bodies are unchanged; malformed replies that
+previously passed are intentionally refused. Revalidate against your registry
+before rollout. Python source gets matching decision hardening but not this
+directory API; this release does not restore PyPI distribution.
+
+## Signed lifecycle receipts (opt-in)
+
+`submitReceipt()` still sends `pg.receipt.v2` by default. A provider with an
+Ed25519 public key registered on its PRAMPTA organization can opt into
+`pg.receipt.v3`, which signs the reported lifecycle moment. Keep the matching
+32-byte private key in a **server-side secret**, never in browser code:
 
 ```typescript
-const prompts = await prampta.myPrompts();
-// Returns: Prompt[]
+await pg.submitReceipt(decision, {
+  outputHash: outputSha256,
+  eventType: "output_accepted", // or preview, output_delivered, output_published
+  providerSigningKeyHex: process.env.PRAMPTA_PROVIDER_SIGNING_KEY_HEX,
+});
 ```
 
-#### `register(ppCode, options?)`
+The SDK signs locally and sends only the signature. A receipt records what the
+provider attests; it does not prove every use was reported, that the output
+complied with rights, or that a payment is due. Do not use an unregistered key:
+the API will reject its signature. Existing v2 integrations are unchanged.
 
-Register an existing PP code to your account.
+## C2PA Bridge & Anchored Audit Log (PRE-GEN v1.1)
 
 ```typescript
-const { registered, prompt } = await prampta.register('PP-3YGBM5V0HN-4');
+import { verifyMerkleProof } from "@prampta/sdk";
+
+// After verifyGeneration() + submitReceipt(), get a signed assertion to
+// embed in your own C2PA manifest — PRAMPTA does not build the manifest.
+const assertion = await pg.createAssertion(decision.decisionId);
+
+// Anyone (not just you) can later verify a decision's audit event was
+// included in a published Merkle root, entirely offline:
+const proof = await pg.getInclusionProof(eventId);
+const root = await pg.getMerkleRoot();
+const ok = await verifyMerkleProof(
+  proof.event_hash as string,
+  proof.proof as any,
+  root.root_hash as string,
+);
 ```
 
-#### `healthCheck()`
+## Security Features
 
-Check API connectivity and authentication.
+- **Ed25519 signature verification** on every decision (via `@noble/ed25519`)
+- **Prompt hash binding** — decision is bound to the exact prompt (SHA-256)
+- **Context binding** — decision cannot be replayed for different subject/provider/licensee/modality
+- **Key fingerprint validation** — operator_key_id matches pinned public key
+- **TTL validation** — expired decisions are rejected
+- **Fail-closed** — any error defaults to deny
 
-```typescript
-const health = await prampta.healthCheck();
-// Returns: { healthy: boolean, latencyMs: number, authenticated: boolean }
-```
 
-### Request Cancellation
+## Key Pinning & Rotation (trust anchor)
 
-All methods accept an optional `signal` for cancellation:
+Signature verification is only meaningful against a key you obtained out of
+band. **Pin the operator key** — do not rely on the key the API hands you:
 
 ```typescript
-const controller = new AbortController();
-
-// Cancel after 5 seconds
-setTimeout(() => controller.abort(), 5000);
-
-try {
-  const prompt = await prampta.decode('PP-xxx', {
-    signal: controller.signal,
-  });
-} catch (err) {
-  if (err.message === 'Request was cancelled') {
-    console.log('Request cancelled');
-  }
-}
+const pg = new Prampta({
+  baseUrl: "https://api2.prampta.com",
+  providerId: "my-ai-service",
+  licenseeId: "acme-corp",
+  token: "your-provider-credential-secret", // NOT a pair token — see Authentication
+  operatorPublicKeyHex: "<pinned key from PRAMPTA docs>",
+});
 ```
 
-### Error Handling
+- A decision is trusted only when signed by a pinned key. A decision signed by
+  an **unpinned** key fails closed with an actionable error (no silent trust).
+- **Rotation without downtime:** pin the current *and* the announced next key
+  (comma/space separated). When PRAMPTA rotates, the new key is already trusted.
+- **No pinned key** → trust-on-first-use: the SDK still verifies but logs a
+  warning. The signature proves consistency, not authenticity. Never ship
+  production this way.
+
+## Configuration
+
+| Parameter | Env Var | Required | Description |
+|-----------|---------|----------|-------------|
+| `baseUrl` | `PRAMPTA_BASE_URL` | Yes | Registry API URL |
+| `providerId` | `PRAMPTA_PROVIDER_ID` | Yes | Your provider ID |
+| `licenseeId` | `PRAMPTA_LICENSEE_ID` | For licensed use | Connected user's PRAMPTA licensee ID; omit for unlicensed personal use |
+| `token` | `PRAMPTA_TOKEN` | Yes | Runtime credential (`ProviderCredential` secret) — see [Authentication](#authentication) |
+| `operatorPublicKeyHex` | `PRAMPTA_OPERATOR_PUBLIC_KEY` | No | Pinned operator key (recommended for production) |
+| `timeoutMs` | — | No | Default `3000`. Request timeout in ms. |
+| `failClosed` | — | No | Default `true`. Deny on any verification error. |
+| `verifyDecisionSignature` | — | No | Default `true`. Set `false` only for local dev. |
+
+## Error Handling
 
 ```typescript
-import { Prampta, PramptaError } from '@prampta/sdk';
+import { Prampta, PramptaRefusalError, PramptaSignatureError } from "@prampta/sdk";
 
 try {
-  const prompt = await prampta.decode('PP-invalid');
-} catch (err) {
-  if (err instanceof PramptaError) {
-    console.error(`API error ${err.status}: ${err.message}`);
-    
-    if (err.status === 404) {
-      console.log('Prompt not found');
-    } else if (err.status === 429) {
-      console.log('Rate limited, try again later');
-    } else if (err.status === 401) {
-      console.log('Invalid API key');
-    }
+  await pg.assertAllowed("subject-id", { prompt: "...", modality: "image" });
+} catch (e) {
+  if (e instanceof PramptaRefusalError) {
+    // License denial — e.reason has the code (PG_NO_LICENSE, PG_SCOPE_VIOLATION, etc.)
+    console.log(e.reason);
+  } else if (e instanceof PramptaSignatureError) {
+    // Operator signature invalid — potential MITM
+    alert("Security: tampered decision");
   }
 }
 ```
 
-## Types
+## Pre-hashed Prompts
 
-```typescript
-interface Prompt {
-  id: string;
-  ppCode: string;
-  title: string;
-  content: string;
-  category: string;
-  tags: string[];
-  authorName: string | null;
-  uses: number;
-  likes: number;
-  visibility: 'public' | 'private';
-  createdAt: number;
-  media?: Record<string, string>;
-}
+If you hash prompts yourself (e.g., for privacy), pass `promptHash` instead of `prompt`:
 
-interface CreateOptions {
-  content: string;     // 10-50,000 characters
-  title?: string;      // Max 200 characters
-  media?: Record<string, string>; // Base64 data URLs
-}
+```typescript
+import { hashPrompt } from "@prampta/sdk";
 
-interface SearchOptions {
-  query?: string;
-  category?: 'development' | 'design' | 'marketing' | 'data' | 'writing' | 'business';
-  limit?: number;  // 1-100
-  page?: number;
-}
+const hash = await hashPrompt("Da Vinci in a documentary");
+const result = await pg.verify("leonardo-da-vinci", {
+  promptHash: hash,
+  modality: "image",
+});
 ```
 
-## Examples
+## API Reference
 
-### With Express.js
+### `new Prampta(config)`
 
-```typescript
-import express from 'express';
-import { Prampta } from '@prampta/sdk';
-
-const app = express();
-const prampta = new Prampta({ apiKey: process.env.PRAMPTA_API_KEY! });
-
-app.get('/prompt/:code', async (req, res) => {
-  try {
-    const prompt = await prampta.decode(req.params.code);
-    res.json(prompt);
-  } catch (err) {
-    res.status(err.status || 500).json({ error: err.message });
-  }
-});
-```
+Creates a client instance.
 
-### With Next.js API Routes
+### `pg.verify(subjectId, options)`
 
-```typescript
-// app/api/prompts/route.ts
-import { NextResponse } from 'next/server';
-import { Prampta } from '@prampta/sdk';
-
-const prampta = new Prampta({ apiKey: process.env.PRAMPTA_API_KEY! });
-
-export async function GET(request: Request) {
-  const { searchParams } = new URL(request.url);
-  const query = searchParams.get('q') || '';
-  
-  const result = await prampta.search({ query });
-  return NextResponse.json(result);
-}
-```
+Returns `Promise<SignedDecision>`:
+- `allowed` — generation authorized
+- `reason` — refusal code (`PG_NO_LICENSE`, `PG_SCOPE_VIOLATION`, `PG_SUBJECT_OPTED_OUT`)
+- `licenseId` — the authorizing license
+- `decisionId` — unique decision ID for audit
+- `obligations` — required obligations (attribution, watermark, etc.)
+- `operatorSignature` — Ed25519 signature over decision
 
-### Batch Operations
+### `pg.assertAllowed(subjectId, options)`
 
-```typescript
-const codes = ['PP-xxx', 'PP-yyy', 'PP-zzz'];
+Same as `verify()` but throws `PramptaRefusalError` if not allowed.
 
-// Parallel fetching with error handling
-const results = await Promise.allSettled(
-  codes.map(code => prampta.decode(code))
-);
+### `pg.health()` / `pg.version()`
 
-const prompts = results
-  .filter((r): r is PromiseFulfilledResult<Prompt> => r.status === 'fulfilled')
-  .map(r => r.value);
-```
+Registry health check and version info.
 
-## Rate Limits
+## Connect Step 1: reporting without authorization
 
-| Limit | Value |
-|-------|-------|
-| Requests per minute | 200 |
-| Requests per day | 5,000 |
-| Max prompt size | 50,000 chars |
-| Max media per prompt | 8 files |
-| Max media size | 2MB per file |
+SDK 0.6.0 adds `PramptaReporter` (Node/server only). Check the installed package
+version before using it. Publishing the SDK and deploying the backend are separate
+steps; this API still requires the `/v1/observations` endpoint on your server.
 
-The SDK automatically handles rate limiting with retries.
+```ts
+import { PramptaReporter } from '@prampta/sdk';
 
-## License
+const reporter = new PramptaReporter({
+  baseUrl: process.env.PRAMPTA_BASE_URL!,
+  providerId: process.env.PRAMPTA_PROVIDER_ID!,
+  token: process.env.PRAMPTA_TOKEN!,
+  outbox: durableOutbox, // Your DB/job-queue adapter, not an in-memory array.
+});
+await reporter.report({
+  eventKey: 'job-123:created', outputId: 'job-123', subjectId: 'selected-subject',
+  occurredAt: '2026-09-21T10:00:00Z', output: outputBytes,
+});
+// Your persistent worker calls reporter.deliver(savedObservation).
+```
 
-MIT
+`report` persists via `ObservationOutbox.put`, without contacting PRAMPTA. That
+adapter must atomically accept identical replays and reject changed payloads
+under the same event ID, separately for each provider/environment. The original
+eventKey and occurredAt must be stable across retries. Raw output stays local;
+for large video use outputHash computed by your streaming storage pipeline.
+The SDK does not download URLs. Keep credentials server-side.
+
+`deliver` performs one bounded attempt. Acknowledge `accepted`; retain and
+reschedule `retry` (respect retryAfterMs, add exponential backoff and jitter);
+quarantine and alert on `rejected`. Never silently discard failed events.
+Storage errors reject `report`; retry the completion job without regenerating.
+No in-memory background delivery guarantee is implied.
+
+No licensee account or Pair is required. This does NOT grant permission, record
+payment, verify content or alter `assertAllowed` behavior. Use the existing
+`matchSubjects` export for local candidate discovery, not automatic claims that
+every name mentioned in a prompt appears in the output. Step 2 remains the
+separate authorization/licensing flow described above.
+
+## Source-only authority experiment (not shipped)
+
+The scoped-authority prototype in `src/experimental*` and its tests remain in
+this repository for review. They are non-normative drafts, not part of the
+`@prampta/sdk` 0.7.0 package. The package builds and exports
+only its stable root API: neither `@prampta/sdk/experimental` nor
+`@prampta/sdk/experimental/node` is available to package consumers.
+
+See `spec/drafts/` for the proposed formats and limits. The experimental backend
+bridge lives on branch `experimental/authority-control-plane`, not on `main`.
+No production authority issuance, protected signing provision or certification
+is implied by these sources or tests.