@licensefoundry/sdk

TypeScript SDK for licensefoundry — issuance, verification, and CoMP-shaped translation of W3C Verifiable Credentials (JWT-VC encoded, Ed25519-signed).

Built in: Phase 5 of /docs/path-c-rebuild-plan.md.

Install

npm install @licensefoundry/sdk

Requires Node.js ≥ 18.

Quick start

import { LicenseFoundryClient, CapabilityNotEnabledError, VerificationError } from "@licensefoundry/sdk";

const lf = new LicenseFoundryClient({
  baseUrl: "https://api.licensefoundry.com",
  apiKey: process.env.LICENSEFOUNDRY_API_KEY!,
  // Production verifiers MUST list only their production issuer DID:
  acceptedIssuers: ["did:web:licensefoundry.com"],
});

// Issue a credential
try {
  const cred = await lf.issuer.issueCredential({
    assetId: "...",
    rights: {
      train: { granted: true, scope: { modelFamily: "open-source" } },
      commercial: { granted: true },
    },
    scope: {
      audience: "single_product",
      productId: "my-rag",
      jurisdiction: ["US"],
      attribution: { required: true },
    },
  });
  console.log(cred.credentialJwt);
} catch (e) {
  if (e instanceof CapabilityNotEnabledError) {
    showUpgradeModal({ plan: e.requiredPlan, url: e.upgradeUrl });
  } else throw e;
}

// Verify a credential offline (uses cached JWKS + Status List)
const result = await lf.verifier.verify(someJwt);
if (!result.valid) {
  console.error("invalid:", result.errors);
}

Public surface

| Module | Use for | | ------------ | -------------------------------------------------------------------------- | | lf.issuer | registerAsset, issueCredential, revokeCredential, status lookups | | lf.verifier| Offline verification with cached JWKS and Status List 2021 | | comp.* | CoMP-shaped translation: fromCredential(vc), satisfies(vc, query) |

The customer-facing API uses canonical Path C field names (train, rag, embed, display, eval, derive, commercial). CoMP terminology (function, subfn, ause, licensedur, etc.) is opt-in via the comp.* helpers.

Typed errors

Per /docs/auth-access-flows.md §4.5, HTTP failures surface as typed errors:

| Error | When | | ---------------------------- | --------------------------------------------------------- | | AuthError | 401 — bad/missing API key | | CapabilityNotEnabledError | 402 with error: capability_not_enabled — upgrade needed | | ScopeDeniedError | 403 — API key scope rejects this action | | NotFoundError | 404 | | ConflictError | 409 — e.g. asset not yet anchored | | ValidationError | 422 | | RateLimitedError | 429 — carries retryAfter | | ServerError | 5xx | | NetworkError | fetch failure / timeout | | VerificationError | thrown by verifier.verifyOrThrow() |

Verification

Verifier performs offline verification per /docs/credential-format.md §7:

1. Parse JWT
2. Resolve issuer (cached did:web → JWKS)
3. EdDSA signature verification
4. Temporal validity
5. @context and issuer accepted-list checks
6. Revocation via Status List 2021 bitstring (cached)

Per /docs/billing-model.md §2, offline verification is free — no metering event. Online verification (calling the issuer's /v1/credentials/verify endpoint) is metered.

Specs that govern this SDK

• /docs/credential-format.md — wire format and verification
• /docs/comp-mapping.md — CoMP translation
• /docs/auth-access-flows.md §4.5 — typed error contracts
• /docs/billing-model.md §2 — what is metered

Develop

npm install
npm test          # vitest run
npm run build     # tsc → dist/
npm run lint      # tsc --noEmit