@prampta/sdk 0.4.0 → 0.8.0

package/README.md

@@ -8,7 +8,33 @@ Pre-generation authorization for AI content. Verifies operator Ed25519 signature
 npm install @prampta/sdk
 ```
 
-Requires Node.js ≥ 18 (uses native `crypto.subtle` for SHA-256).
+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
 
@@ -18,22 +44,25 @@ import { Prampta } from "@prampta/sdk";
 const pg = new Prampta({
   baseUrl: "https://api2.prampta.com",
   providerId: "my-ai-service",
-  licenseeId: "acme-corp",
-  token: "pair-token",
+  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
 });
 
-// Option 1: Assert — throws if denied (fail-closed)
-await pg.assertAllowed("leonardo-da-vinci", {
-  prompt: "Da Vinci in a documentary",
+// 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: "gpt-image-1",
+  model: "your-model",
+  intendedUse: { useCase: "research" },
 });
 
 // Option 2: Verify — returns decision object
-const result = await pg.verify("leonardo-da-vinci", {
-  prompt: "Da Vinci in a documentary",
+const result = await pg.verify("sbx-allowed", {
+  prompt: "A sandbox portrait",
   modality: "image",
-  model: "gpt-image-1",
+  model: "your-model",
+  intendedUse: { useCase: "research" },
 });
 
 if (result.allowed) {
@@ -43,6 +72,176 @@ if (result.allowed) {
 }
 ```
 
+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).
+
+## Strict license-backed authorization (0.7.0)
+
+`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 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.
+```
+
+## The whole cycle in one call (0.8.0)
+
+`generateAuthorized` does what every integration otherwise writes by hand:
+
+- asks fresh for **every subject in the output** (a person, a voice, a brand…)
+  and generates only if **all** of them return a licence-backed `allow`;
+- never reuses a stored allow, and checks each is still live right before it
+  starts, so a pause or revocation stops the next generation;
+- files one receipt per subject;
+- gives the allows back (`releaseDecision`) when a subject refuses or your
+  `generate` throws, so a failed job does not use up a licence limit;
+- with a `journal` (your own database), never generates twice after a crash:
+  a repeat call resends missing receipts, or refuses a job that crashed
+  midway instead of rerunning it.
+
+```typescript
+const result = await pg.generateAuthorized(
+  { subjectIds: [personCode, voiceCode], generationId: jobId, promptHash,
+    modality: "video", model: modelName,
+    intendedUse: { useCase: "commercial", rights: ["output_generation"] } },
+  async (decisions) => {
+    // Apply every decision's obligations here. Throw only if nothing was produced.
+    const video = await render(prompt);
+    return { output: video, outputBytes: video.bytes };
+  },
+  { journal: { get: (id) => db.jobs.get(id), put: (e) => db.jobs.put(e) } },
+);
+if (result.unreported.length) retryLater(jobId); // receipts are resent by calling again
+```
+
+It uses `assertLicensed` (pinned operator keys required). The journal needs
+`put` to resolve only after a durable write.
+
+## Check answers against PRE-GEN (recommended)
+
+```typescript
+import { Prampta, loadPregenDirectory } from "@prampta/sdk";
+
+const pregenDirectory = await loadPregenDirectory({ previous: saved }); // steward key built in
+saved = pregenDirectory.toJSON();                                       // keep it for next start
+
+const registry = new Prampta({ baseUrl: "https://api2.prampta.com", providerId, token, licenseeId,
+  pregenDirectory });
+```
+
+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`.
+
+## Optional namespace trust with your own root (0.7.0)
+
+```typescript
+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,
+});
+```
+
+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
+await pg.submitReceipt(decision, {
+  outputHash: outputSha256,
+  eventType: "output_accepted", // or preview, output_delivered, output_published
+  providerSigningKeyHex: process.env.PRAMPTA_PROVIDER_SIGNING_KEY_HEX,
+});
+```
+
+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.
+
+## C2PA Bridge & Anchored Audit Log (PRE-GEN v1.1)
+
+```typescript
+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,
+);
+```
+
 ## Security Features
 
 - **Ed25519 signature verification** on every decision (via `@noble/ed25519`)
@@ -63,7 +262,7 @@ const pg = new Prampta({
   baseUrl: "https://api2.prampta.com",
   providerId: "my-ai-service",
   licenseeId: "acme-corp",
-  token: "pair-token",
+  token: "your-provider-credential-secret", // NOT a pair token — see Authentication
   operatorPublicKeyHex: "<pinned key from PRAMPTA docs>",
 });
 ```
@@ -82,8 +281,8 @@ const pg = new Prampta({
 |-----------|---------|----------|-------------|
 | `baseUrl` | `PRAMPTA_BASE_URL` | Yes | Registry API URL |
 | `providerId` | `PRAMPTA_PROVIDER_ID` | Yes | Your provider ID |
-| `licenseeId` | `PRAMPTA_LICENSEE_ID` | Yes | Licensee ID |
-| `token` | `PRAMPTA_TOKEN` | Yes | Pair auth token |
+| `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. |
@@ -144,3 +343,57 @@ Same as `verify()` but throws `PramptaRefusalError` if not allowed.
 ### `pg.health()` / `pg.version()`
 
 Registry health check and version info.
+
+## Connect Step 1: reporting without authorization
+
+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.
+
+```ts
+import { PramptaReporter } from '@prampta/sdk';
+
+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).
+```
+
+`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.