@prampta/sdk 0.4.0 → 0.7.0

package/dist/index.d.mts

@@ -1,3 +1,125 @@
+import { Directory } from '@pregen/verify';
+export { Directory as PregenDirectory, loadDirectory as loadPregenDirectory } from '@pregen/verify';
+
+/** PRE-GEN v5 serialization. Do not silently replace it with JCS: existing
+ * signatures use these bytes. A new canonicalization needs a new version. */
+declare function canonicalJson(obj: unknown): string;
+
+declare class RegistryDirectoryError extends Error {
+    constructor(message: string);
+}
+interface RegistryDirectoryOptions {
+    /** Trust anchor obtained independently, NOT from the directory itself. */
+    stewardPublicKeyHex: string;
+    /** Highest accepted sequence, persisted by the application across restarts. */
+    minSequence?: number;
+    /** Last accepted state from durable storage; detects same-sequence forks. */
+    previousSnapshot?: {
+        sequence: number;
+        hash: string;
+    };
+}
+/** Immutable, signature-verified directory snapshot. No network discovery,
+ * automatic root replacement, registry accreditation or rights attestation. */
+declare class TrustedRegistryDirectory {
+    #private;
+    readonly sequence: number;
+    readonly snapshotHash: string;
+    private constructor();
+    static verify(input: unknown, options: RegistryDirectoryOptions): Promise<TrustedRegistryDirectory>;
+    private registryFor;
+    /** V-11: checked before forwarding a provider's credential to an endpoint. */
+    assertEndpoint(subject: string, baseUrl: string): void;
+    /** V-10: use only AFTER independently verifying the object's signature. */
+    assertSigner(code: string, keyId: string): void;
+    assertDecision(subject: string, license: string | null, keyId: string, baseUrl: string): void;
+}
+
+interface LicenseSignatureInput {
+    body: Record<string, unknown>;
+    licenseId: string;
+    subjectPublicKeyHex: string;
+    subjectSignatureHex: string;
+    operatorPublicKeyHex: string;
+    operatorSignatureHex: string;
+}
+/** V-9 crypto check only. Obtain keys independently and check namespace,
+ * authority, status and scope separately; true is NOT a proof of consent. */
+declare function verifyLicenseSignatures(input: LicenseSignatureInput): Promise<{
+    subjectValid: boolean;
+    operatorValid: boolean;
+}>;
+
+/** Connect Step 1. Server-side only; reporting NEVER authorizes generation. */
+interface Observation {
+    schema_version: "pg.observation.v1";
+    event_id: string;
+    output_id: string;
+    subject_id: string;
+    event_type: "output.created" | "output.modified" | "output.published" | "publication.removed";
+    output_hash: string;
+    occurred_at: string;
+    declared_purpose: "personal" | "commercial" | "educational" | "research" | "editorial" | "unknown";
+    parent_output_hash?: string;
+    publication_url?: string;
+}
+interface ReportInput {
+    /** Stable provider job/event key. Different publications/edits need different keys. */
+    eventKey: string;
+    outputId: string;
+    /** Provider-confirmed association, NOT automatically a text matcher hit. */
+    subjectId: string;
+    /** Original event time, retained across retries. */
+    occurredAt: string;
+    eventType?: Observation["event_type"];
+    purpose?: Observation["declared_purpose"];
+    /** Actual output bytes or text, never a URL to be downloaded. Stays local. */
+    output?: Uint8Array | string;
+    /** For large files, compute incrementally in your storage pipeline. */
+    outputHash?: string;
+    parentOutputHash?: string;
+    publicationUrl?: string;
+}
+interface ObservationOutbox {
+    /** Persist atomically under event_id; same payload is a no-op, changed payload
+     * must reject. Namespace storage by provider AND environment. Resolve only
+     * after durable commit. Implement using the provider's existing DB/job queue. */
+    put(event: Observation): Promise<void>;
+}
+type DeliveryResult = {
+    status: "accepted";
+    observationId: string;
+} | {
+    status: "retry";
+    httpStatus?: number;
+    retryAfterMs: number;
+} | {
+    status: "rejected";
+    httpStatus: number;
+};
+declare class PramptaReporter {
+    private readonly config;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(config: {
+        baseUrl: string;
+        providerId: string;
+        token: string;
+        outbox: ObservationOutbox;
+        timeoutMs?: number;
+    });
+    /** No PRAMPTA network call: hash locally and commit to the durable outbox.
+     * A storage failure is surfaced, never reported as success. Run from the
+     * provider's generation-completed job, not as an authorization gate. */
+    report(input: ReportInput): Promise<{
+        status: "queued";
+        eventId: string;
+    }>;
+    /** One bounded attempt by your queue worker. Keep/retry on `retry`, quarantine
+     * on `rejected`, acknowledge only `accepted`. Never changes /verify behavior. */
+    deliver(event: Observation): Promise<DeliveryResult>;
+}
+
 /**
  * PRAMPTA SDK for TypeScript / Node.js
  *
@@ -11,26 +133,47 @@
  * const pg = new Prampta({
  *   baseUrl: "https://api2.prampta.com",
  *   providerId: "my-ai-service",
- *   licenseeId: "acme-corp",
- *   token: "pair-token",
+ *   licenseeId: "lic-sandbox", // synthetic sandbox fixture only
+ *   // Your runtime credential's `exchange_secret` — from your provider
+ *   // application's verify-email/verify-domain response (see the Provider
+ *   // Connect Guide). NOT the legacy shared pair token; see `token` below.
+ *   token: process.env.PRAMPTA_TOKEN,
  * });
  *
  * // Throws if denied — fail-closed by default
- * await pg.assertAllowed("leonardo-da-vinci", {
- *   prompt: "Da Vinci in a documentary",
+ * await pg.assertAllowed("sbx-allowed", {
+ *   prompt: "A sandbox portrait",
  *   modality: "image",
- *   model: "gpt-image-1",
+ *   model: "your-model",
+ *   intendedUse: { useCase: "research" },
  * });
  * ```
  */
+
 interface PramptaConfig {
     /** The PRAMPTA registry URL. Falls back to PRAMPTA_BASE_URL env var. */
     baseUrl?: string;
     /** Your provider ID. Falls back to PRAMPTA_PROVIDER_ID env var. */
     providerId?: string;
-    /** The licensee ID. Falls back to PRAMPTA_LICENSEE_ID env var. */
+    /** The licensee ID (`prampta_licensee_id` from Connect AI). Falls back to
+     * PRAMPTA_LICENSEE_ID. Optional: without it, verify is a provider-level
+     * check that can only answer `not_blocked` for `useCase: "personal"`. */
     licenseeId?: string;
-    /** The pair authentication token. Falls back to PRAMPTA_TOKEN env var. */
+    /**
+     * The runtime bearer credential. This is your `ProviderCredential`'s
+     * `exchange_secret` — issued inline by `verify-email` (sandbox) or
+     * `verify-domain/confirm` (production) during provider onboarding.
+     * The `prampta_connection_token` returned by Connect AI is NOT accepted
+     * for production runtime calls.
+     * Falls back to PRAMPTA_TOKEN env var.
+     *
+     * The legacy shared PAIR TOKEN also works here ONLY while the server is
+     * running in `PILOT_MODE` (pre-migration deployments) — production
+     * deployments with the trust flags on (the v1.0.0 default) reject it with
+     * `PG_NO_PAIR`. Do not build new integrations against the pair token; it
+     * exists solely so an already-connected provider keeps working during
+     * migration. See docs/PRAMPTA-Provider-Connect-Guide-2026-08.md.
+     */
     token?: string;
     /** Request timeout in milliseconds (default 3000). */
     timeoutMs?: number;
@@ -65,6 +208,27 @@ interface PramptaConfig {
      * Set to false ONLY for local development — never in production.
      */
     verifyDecisionSignature?: boolean;
+    /**
+     * If true, verify() throws PramptaSchemaError LOCALLY — before any network
+     * call — when neither providerUserId nor providerIdentityLinkId was
+     * supplied. Off by default (most integrations have legitimately unbound
+     * calls); turn it on once your integration always acts for a specific end
+     * user, so a caller that forgot to pass one fails fast and loud in your own
+     * code rather than silently reaching the server as an "unbound" request.
+     * Independent of, and a cheaper backstop for, the server-side
+     * REQUIRE_PROVIDER_USER_BINDING enforcement — this catches the mistake
+     * before spending a round-trip. Default false.
+     */
+    requireUserBinding?: boolean;
+    /** Out-of-band verified namespace directory. Opt-in while the public
+     * steward root is not yet published. Requires pinned operator keys. */
+    registryDirectory?: TrustedRegistryDirectory;
+    /** The PRE-GEN directory from `loadPregenDirectory()`, with the steward key built in.
+     * Before a request the SDK checks that `baseUrl` owns the subject's namespace; on an
+     * `allow` it also runs @pregen/verify `checkDecision`: the signing key must be one the
+     * directory lists for the license's namespace (origin keys pinned), on top of the checks
+     * below. Recommended over `registryDirectory`. */
+    pregenDirectory?: Directory;
 }
 interface VerifyRequest {
     /** Subject to verify authorization for. */
@@ -84,7 +248,43 @@ interface VerifyRequest {
         projectName?: string;
         categories?: string[];
         territory?: string;
+        /** Commercial-model campaign binding — required by premium billing terms. */
+        campaignId?: string;
+        /** The use-case tier: "personal" | "educational" | "research" |
+         * "editorial" | "commercial". Personal use with no licence answers
+         * disposition "not_blocked" only when this is declared (NMP Q13). */
+        useCase?: string;
+        /** Rights requested in addition to the generation modality. */
+        rights?: string[];
     };
+    /** ── Provider-user binding (prampta.identity.v2) ──
+     * WHO you are acting for. Optional, so existing integrations are
+     * unaffected — but once supplied it is held to: it must resolve to an
+     * identity link PRAMPTA verified, and a licence belonging to a different
+     * end user is refused. Supply either identifier (or both — they must then
+     * describe the same person). */
+    providerUserId?: string;
+    providerIdentityLinkId?: string;
+    /** Your own id for this generation attempt. Echoed into the decision so a
+     * later receipt can be tied to it without a provider-side lookup table. */
+    generationId?: string;
+    /** Lets you safely retry a preflight you are unsure landed. */
+    idempotencyKey?: string;
+    /** Links this call to a prior reportDetection()/confirmDetection() advisory
+     * record, purely for audit — never used to decide the outcome. */
+    detectionId?: string;
+    /** Where to send the end user back to after they buy/request a licence via
+     * the returned decision's `remediation.url` (set only on PG_NO_LICENSE) —
+     * same idea as Connect AI's connect_return_url. Omit to leave them on
+     * prampta.com after they act. */
+    returnUrl?: string;
+    /** Protocol version negotiation: declares the decision schema THIS CALL
+     * expects (e.g. "pg.decision.v1"). A mismatch refuses with 409 before any
+     * licensing work happens, instead of silently misreading a future schema.
+     * Optional — omit to keep today's behavior. Discover the server's current
+     * version via GET /version -> protocol_versions.decision_schema. See
+     * docs/PRAMPTA-Protocol-Versions.md. */
+    expectedSchemaVersion?: string;
 }
 /** Options for the flat `pg.verify(subjectId, options)` convenience call. */
 interface VerifyOptions extends Omit<VerifyRequest, "subjectId"> {
@@ -93,6 +293,9 @@ interface VerifyOptions extends Omit<VerifyRequest, "subjectId"> {
     productName?: string;
     projectName?: string;
     territory?: string;
+    campaignId?: string;
+    useCase?: string;
+    rights?: string[];
 }
 interface SignedDecision {
     schemaVersion: string;
@@ -120,6 +323,42 @@ interface SignedDecision {
      * consented | verified. "self" is only the registrant's own claim. */
     subjectAuthority: string;
     denied: boolean;
+    /** Outcome (§8): "allow" | "deny" | "review" | "not_blocked". `allowed` stays
+     * the boolean; a REVIEW is allowed=false + disposition="review" — hold for a
+     * human, not a flat refusal. "not_blocked" (NMP Q13) is personal use with no
+     * licence: PRAMPTA does not object but grants nothing (reason
+     * PG_STD_TRACKING_ONLY). Older code reading only `allowed` fails closed. */
+    disposition: string;
+    /** Policy version that produced this decision. */
+    policyVersion: string;
+    /** §7 freshness controls. `revocationEpoch` is the subject's epoch at
+     * issuance — compare it against GET /subjects/{id}/epoch to learn cheaply
+     * whether anything happened since (revoke, dispute, lifecycle change)
+     * without re-running verify(). `maxCacheAgeSeconds` and `cacheScope` say
+     * whether and how long this exact decision may be reused without a live
+     * re-check; only a plain ALLOW is ever cacheable. */
+    revocationEpoch: number;
+    maxCacheAgeSeconds: number;
+    cacheScope: string;
+    /** Provider-user binding: "verified" — bound to an end-user identity
+     * PRAMPTA verified; "unbound" — no end user was asserted; "invalid" — an
+     * assertion was made and failed (always accompanies a deny). */
+    providerUserBinding: string;
+    /** Which identity link was used, when one was. */
+    providerIdentityLinkId: string;
+    /** Echoed back from the request, for receipt matching. */
+    generationId: string;
+    /** Echoed back from the request — links to a detection advisory record. */
+    detectionId: string;
+    /** Set only when reason === "PG_NO_LICENSE": a direct link to buy/request a
+     * licence for this exact subject, plus the one canonical explanation text
+     * (show it before redirecting — every integration should read the same
+     * wording). null on every other outcome, including allow and refusals a
+     * licence purchase would not fix. */
+    remediation: {
+        url: string;
+        message: string;
+    } | null;
 }
 interface SubjectInfo {
     subjectId: string;
@@ -191,16 +430,22 @@ declare const SOFT_REFUSAL_CODES: Set<string>;
  * `Prampta.hashPrompt` so it can be imported directly. */
 declare function hashPrompt(prompt: string): Promise<string>;
 /**
- * Canonical JSON — deterministic serialization matching Python's
- * `json.dumps(obj, sort_keys=True, separators=(",",":"), ensure_ascii=False)`.
- * Required for signature verification across languages.
+ * Client-side Merkle inclusion-proof verification (PRE-GEN v1.1 addendum
+ * §10, Anchored Audit Profile). Mirror of the registry's own
+ * `app/core/merkle.py` — same algorithm, same odd-node handling — so a
+ * proof from `Prampta.getInclusionProof()` can be checked entirely
+ * offline against a root hash you already trust, without the registry
+ * being a party to its own audit.
  *
- * Exported so external verifiers can rebuild signed bodies and so the
- * cross-implementation spec test vectors (spec/test-vectors) can pin it.
- * Field names in signed protocol bodies are ASCII by construction — key
- * sorting is identical to Python's code-point sort in that range.
+ * `proof` is the array PRAMPTA returns as `inclusion_proof.proof` — each
+ * step `{hash: <sibling hash>, position: "left"|"right"}`. Returns true
+ * only if `leafHash` is genuinely one of the leaves committed to by
+ * `rootHash`.
  */
-declare function canonicalJson(obj: unknown): string;
+declare function verifyMerkleProof(leafHash: string, proof: Array<{
+    hash: string;
+    position: "left" | "right";
+}>, rootHash: string): Promise<boolean>;
 /** One entry of the /v1/subjects/index detection index. */
 interface SubjectIndexEntry {
     subject_id: string;
@@ -232,11 +477,16 @@ declare class Prampta {
     private readonly failClosed;
     private readonly verifySignature;
     private readonly enforce;
+    private readonly requireUserBinding;
+    private readonly registryDirectory?;
+    private readonly pregenDirectory?;
     private pinnedKeys;
     private keySetCache;
     private keySetPromise;
     private tofuWarned;
     constructor(config?: PramptaConfig);
+    /** V-11: a PG code is answered only by the registry that owns its namespace. */
+    private assertPregenEndpoint;
     /** Fetch /keys and check it is self-signed by its current key. Cached. */
     private fetchVerifiedKeySet;
     /**
@@ -262,6 +512,27 @@ declare class Prampta {
     matchSubjects(text: string, opts?: {
         forceRefresh?: boolean;
     }): Promise<SubjectIndexEntry[]>;
+    /** Record what a local text match found for a prompt, BEFORE the user
+     * answers. Purely advisory — creates no entitlement or licence. Pass the
+     * returned detectionId to confirmDetection() and optionally to verify(). */
+    reportDetection(promptHash: string, candidateSubjectIds: string[]): Promise<{
+        detectionId: string;
+        status: string;
+        candidateSubjectIds: string[];
+        confirmedSubjectId: string | null;
+        createdAt: string;
+        confirmedAt: string | null;
+    }>;
+    /** Record what the user actually said. `subjectId` undefined/null means
+     * they rejected every candidate. Still advisory-only. */
+    confirmDetection(detectionId: string, subjectId?: string | null): Promise<{
+        detectionId: string;
+        status: string;
+        candidateSubjectIds: string[];
+        confirmedSubjectId: string | null;
+        createdAt: string;
+        confirmedAt: string | null;
+    }>;
     /**
      * Verify operator Ed25519 signature over decision body.
      * Fails closed on any error.
@@ -279,6 +550,10 @@ declare class Prampta {
      * the prompt hash and the SDK refuses to request unbound ones. */
     verify(subjectId: string, options?: VerifyOptions): Promise<SignedDecision>;
     assertAllowed(subjectId: string, options?: Omit<VerifyRequest, "subjectId">): Promise<SignedDecision>;
+    /** Strict license-backed path. Unlike assertAllowed, this never accepts
+     * reporting-only not_blocked, an internal no-license allow, or monitor mode.
+     * It validates an authorization; it does not prove output compliance. */
+    assertLicensed(subjectId: string, options?: Omit<VerifyRequest, "subjectId">): Promise<SignedDecision>;
     withAuthorization<T>(request: VerifyRequest, generateFn: (decision: SignedDecision) => Promise<T>): Promise<{
         output: T;
         decision: SignedDecision;
@@ -288,9 +563,9 @@ declare class Prampta {
     requestLicense(input: LicenseRequestInput): Promise<LicenseRequestResult>;
     createOutputMetadata(decision: SignedDecision): OutputMetadata;
     /**
-     * Submit a generation receipt AFTER generating — the provider's enforcement
-     * proof, bound to the decision it acted on. Records that this generation was
-     * authorized and executed under the decision's terms (verifiable post-hoc).
+     * Report an output after generation. With a registered provider signing key,
+     * opt into v3 so eventType is bound to the provider's signature. This is a
+     * provider attestation, not proof of complete reporting or actual execution.
      */
     submitReceipt(decision: SignedDecision, result?: {
         outputHash?: string;
@@ -298,7 +573,31 @@ declare class Prampta {
         watermarkEmbedded?: boolean;
         obligationsApplied?: Record<string, unknown>;
         generatedAt?: number;
+        eventType?: "preview" | "output_accepted" | "output_delivered" | "output_published";
+        /** 32-byte Ed25519 private key, hex; keep server-side. Never sent to PRAMPTA. */
+        providerSigningKeyHex?: string;
     }): Promise<Record<string, unknown>>;
+    /**
+     * Get (issuing if needed) the signed `pg.assertion.v1` for a decision this
+     * provider/licensee pair already submitted a receipt for — embed it in
+     * your OWN C2PA manifest (PRAMPTA does not build the manifest itself).
+     * Idempotent: safe to call again for the same decisionId, always returns
+     * the same assertion. Requires `submitReceipt()` to have run first.
+     */
+    createAssertion(decisionId: string): Promise<Record<string, unknown>>;
+    /** Fetch a previously issued assertion. Public — no auth required, since a
+     * third party checking a C2PA manifest's embedded assertion needs to
+     * verify it without going through PRAMPTA's own auth. */
+    getAssertion(decisionId: string): Promise<Record<string, unknown>>;
+    /** The most recently published Merkle root over the audit log. Public,
+     * unauthenticated. */
+    getMerkleRoot(): Promise<Record<string, unknown>>;
+    /** Proof that `eventId` is one of the leaves committed to by a Merkle
+     * root, without downloading the rest of the log. Check it offline with
+     * the standalone `verifyMerkleProof(eventHash, proof, rootHash)` — don't
+     * just trust the 200 response; the proof exists so you don't have to.
+     * Public, unauthenticated. */
+    getInclusionProof(eventId: string): Promise<Record<string, unknown>>;
     health(): Promise<boolean>;
     version(): Promise<Record<string, unknown>>;
     static hashPrompt(prompt: string): Promise<string>;
@@ -313,4 +612,4 @@ declare class Prampta {
     private getOnce;
 }
 
-export { HARD_REFUSAL_CODES, type LicenseRequestInput, type LicenseRequestResult, type OutputMetadata, Prampta, PramptaApiError, type PramptaConfig, PramptaError, PramptaFailClosedError, PramptaNetworkError, PramptaRefusalError, PramptaSchemaError, PramptaSignatureError, PramptaTimeoutError, REFUSAL_DESCRIPTIONS, SOFT_REFUSAL_CODES, type SignedDecision, type SubjectIndexEntry, type SubjectInfo, type VerifyOptions, type VerifyRequest, canonicalJson, hashPrompt, matchSubjects, normalizeForMatch };
+export { type DeliveryResult, HARD_REFUSAL_CODES, type LicenseRequestInput, type LicenseRequestResult, type LicenseSignatureInput, type Observation, type ObservationOutbox, type OutputMetadata, Prampta, PramptaApiError, type PramptaConfig, PramptaError, PramptaFailClosedError, PramptaNetworkError, PramptaRefusalError, PramptaReporter, PramptaSchemaError, PramptaSignatureError, PramptaTimeoutError, REFUSAL_DESCRIPTIONS, RegistryDirectoryError, type RegistryDirectoryOptions, type ReportInput, SOFT_REFUSAL_CODES, type SignedDecision, type SubjectIndexEntry, type SubjectInfo, TrustedRegistryDirectory, type VerifyOptions, type VerifyRequest, canonicalJson, hashPrompt, matchSubjects, normalizeForMatch, verifyLicenseSignatures, verifyMerkleProof };