@c15t/node-sdk 3.0.0-alpha.5 → 3.0.0-alpha.7

package/README.md

@@ -24,7 +24,7 @@ Typed client for hosted and self-hosted c15t backends. Check consent before send
 
 - One `createC15tClient()` call with an explicit backend URL. No environment variables are read
 - Methods resolve to `{ ok: true, data }` or `{ ok: false, error }` and never reject. Error codes are typed per method
-- Key-only methods (`subjects.list`, `experiments.summary`, `legalDocuments.publish`) exist only on a client created with an API key
+- Key-only methods (`consents.check`, `subjects.list`, `experiments.summary`, `legalDocuments.publish`) exist only on a client created with an API key
 - Input is validated before anything is sent, and response dates are `Date` objects
 - Per-attempt timeouts and retries for network errors, timeouts and 408, 429, 500, 502, 503 and 504, honouring `Retry-After`
 - A typed mock client in `@c15t/node-sdk/testing`
@@ -77,8 +77,8 @@ For further information, guides, and examples visit the [reference documentation
 
 | Method | API key |
 | --- | --- |
-| `consents.check({ externalId, types })` | No |
-| `subjects.identify(id, { externalId, identityProvider })` | No |
+| `consents.check({ externalId, types })` | Required |
+| `subjects.identify(id, { externalId, identityProvider, identityToken })` | No; verified only with a key or token |
 | `subjects.get(id, { types })` | No |
 | `subjects.create(input)` | No |
 | `subjects.list({ externalId })` | Required |
@@ -88,6 +88,8 @@ For further information, guides, and examples visit the [reference documentation
 
 Every method takes `{ signal, timeoutMs, headers, retry, requestId }` as its last argument.
 
+`createIdentityToken(user, { signingKey })` is a separate export, not a client method. It signs a token locally for the browser's `identify()`, takes no call options, and throws a `TypeError` on invalid input.
+
 ## Upgrading from v2
 
 `c15tClient()` and the `C15TClient` class are replaced by `createC15tClient()`. Results replace `ResponseContext`, `C15TError` is now `C15tError`, and `subjects.patch` is now `subjects.identify`. See the [migration guide](https://c15t.com/docs/upgrade-v3#update-the-nodejs-sdk).

package/dist/160.js

@@ -5,6 +5,8 @@ const C15T_API_ERROR_CODES = [
     'CONFLICT',
     'DATABASE_ERROR',
     'EXTERNAL_ID_REQUIRED',
+    'IDENTITY_CONFLICT',
+    'IDENTITY_TOKEN_INVALID',
     'INPUT_VALIDATION_FAILED',
     'NOT_FOUND',
     'POLICY_SNAPSHOT_EXPIRED',

package/dist/index.js

@@ -344,6 +344,8 @@ const identifySubject = defineEndpoint({
     errorCodes: [
         'DATABASE_ERROR',
         'EXTERNAL_ID_REQUIRED',
+        'IDENTITY_CONFLICT',
+        'IDENTITY_TOKEN_INVALID',
         'NOT_FOUND'
     ],
     idempotent: true,
@@ -369,7 +371,7 @@ const identifySubject = defineEndpoint({
         ]
 });
 const checkConsent = defineEndpoint({
-    auth: 'none',
+    auth: 'api-key',
     decode: (body, _response, input)=>{
         const value = asObject(body, 'body');
         const results = asObject(value.results, 'results');
@@ -385,7 +387,8 @@ const checkConsent = defineEndpoint({
     errorCodes: [
         'DATABASE_ERROR',
         'EXTERNAL_ID_REQUIRED',
-        'TYPE_REQUIRED'
+        'TYPE_REQUIRED',
+        'UNAUTHORIZED'
     ],
     idempotent: true,
     method: 'GET',
@@ -735,7 +738,7 @@ const path_buildPath = function(template, params) {
     const values = params;
     return template.replace(/:(?<name>[A-Za-z]+)/gu, (_match, name)=>encodeURIComponent(values[name] ?? ''));
 };
-const version = '3.0.0-alpha.5';
+const version = '3.0.0-alpha.7';
 const RETRYABLE_STATUSES = new Set([
     408,
     429,
@@ -1056,9 +1059,45 @@ function createC15tClient(options) {
         }
     };
 }
+const DEFAULT_TTL_SECONDS = 3600;
+const MIN_KEY_BYTES = 32;
+const base64url = (bytes)=>{
+    let binary = '';
+    for (const byte of bytes)binary += String.fromCodePoint(byte);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/u, '');
+};
+const encodeJson = (value)=>base64url(new TextEncoder().encode(JSON.stringify(value)));
+const identity_token_createIdentityToken = async function(user, options) {
+    if ('string' != typeof user?.externalId || '' === user.externalId) throw new TypeError('createIdentityToken: externalId must be a string.');
+    if ('string' != typeof options?.signingKey || new TextEncoder().encode(options.signingKey).length < MIN_KEY_BYTES) throw new TypeError(`createIdentityToken: signingKey must be a string of at least ${MIN_KEY_BYTES} bytes.`);
+    const ttl = options.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+    if (!Number.isSafeInteger(ttl) || ttl <= 0) throw new TypeError('createIdentityToken: ttlSeconds must be a positive integer.');
+    const iat = Math.floor((options.now ?? Date.now)() / 1000);
+    const header = encodeJson({
+        alg: 'HS256',
+        typ: 'JWT'
+    });
+    const claims = {
+        aud: options.audience || 'c15t-identity',
+        exp: iat + ttl,
+        iat,
+        iss: options.issuer || 'c15t',
+        sub: user.externalId
+    };
+    if (void 0 !== user.identityProvider) claims.idp = user.identityProvider;
+    const payload = encodeJson(claims);
+    const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(options.signingKey), {
+        hash: 'SHA-256',
+        name: 'HMAC'
+    }, false, [
+        'sign'
+    ]);
+    const signature = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${header}.${payload}`));
+    return `${header}.${payload}.${base64url(new Uint8Array(signature))}`;
+};
 const result_unwrap = function(result) {
     if (result.ok) return result.data;
     throw result.error;
 };
 export { C15T_API_ERROR_CODES, C15T_CLIENT_ERROR_CODES, C15tError, isC15tError } from "./160.js";
-export { C15tConfigurationError, createC15tClient, result_unwrap as unwrap };
+export { C15tConfigurationError, createC15tClient, identity_token_createIdentityToken as createIdentityToken, result_unwrap as unwrap };

package/dist-types/client.d.ts

@@ -19,29 +19,39 @@ export interface C15tPublicSubjects {
      */
     create: (input: C15tCreateSubjectInput, options?: C15tCallOptions) => Promise<C15tResult<PostSubjectOutput, 'CHOICE_OUT_OF_SCOPE' | 'CHOICE_PREFERENCE_MISMATCH' | 'CONFLICT' | 'DATABASE_ERROR' | 'INPUT_VALIDATION_FAILED' | 'POLICY_SNAPSHOT_EXPIRED' | 'POLICY_SNAPSHOT_INVALID' | 'POLICY_SNAPSHOT_REQUIRED' | 'PURPOSE_NOT_ALLOWED' | 'STALE_POLICY' | 'SUBJECT_CONFLICT'>>;
     /**
-     * Links a subject to your own user id, so `consents.check` and
-     * `subjects.list` can find it. Call it after the visitor signs in.
+     * Links a subject to your own user id. Call it after the visitor signs in.
+     *
+     * `consents.check` and `subjects.list` only find a subject whose link was
+     * verified. A client with an API key verifies every link it makes.
+     * Without a key, pass an `identityToken` from `createIdentityToken`,
+     * or the link is stored unverified.
+     *
+     * An unverified link cannot replace a verified one: that returns
+     * `IDENTITY_CONFLICT`. A token that fails to verify returns
+     * `IDENTITY_TOKEN_INVALID`.
      *
      * @param id - Subject id from the visitor's browser.
-     * @param input - Your user id and, optionally, who issued it.
+     * @param input - Your user id, optionally who issued it, and optionally an
+     * identity token.
      */
-    identify: (id: string, input: C15tIdentifySubjectInput, options?: C15tCallOptions) => Promise<C15tResult<PatchSubjectOutput, 'DATABASE_ERROR' | 'EXTERNAL_ID_REQUIRED' | 'NOT_FOUND'>>;
+    identify: (id: string, input: C15tIdentifySubjectInput, options?: C15tCallOptions) => Promise<C15tResult<PatchSubjectOutput, 'DATABASE_ERROR' | 'EXTERNAL_ID_REQUIRED' | 'IDENTITY_CONFLICT' | 'IDENTITY_TOKEN_INVALID' | 'NOT_FOUND'>>;
 }
 /** `subjects` methods on a client with an API key. */
 export interface C15tSubjects extends C15tPublicSubjects {
     /**
-     * Lists every subject linked to one of your user ids, with their consents.
-     * Needs an API key.
+     * Lists every subject verifiably linked to one of your user ids, with
+     * their consents. Needs an API key.
      */
     list: (query: {
         readonly externalId: string;
     }, options?: C15tCallOptions) => Promise<C15tResult<ListSubjectsOutput, 'DATABASE_ERROR' | 'EXTERNAL_ID_REQUIRED' | 'UNAUTHORIZED'>>;
 }
-/** `consents` methods. */
+/** `consents` methods. Need an API key. */
 export interface C15tConsents {
     /**
      * Reports whether a user has consented to each policy type. Every
-     * requested type appears in `results`, consented or not.
+     * requested type appears in `results`, consented or not. Only subjects
+     * verifiably linked to the user count; see `subjects.identify`.
      *
      * @example
      * ```ts
@@ -54,7 +64,7 @@ export interface C15tConsents {
      * }
      * ```
      */
-    check: <const Types extends readonly [ConsentPolicyType, ...ConsentPolicyType[]]>(input: C15tCheckConsentInput<Types>, options?: C15tCallOptions) => Promise<C15tResult<C15tCheckConsentOutput<Types[number]>, 'DATABASE_ERROR' | 'EXTERNAL_ID_REQUIRED' | 'TYPE_REQUIRED'>>;
+    check: <const Types extends readonly [ConsentPolicyType, ...ConsentPolicyType[]]>(input: C15tCheckConsentInput<Types>, options?: C15tCallOptions) => Promise<C15tResult<C15tCheckConsentOutput<Types[number]>, 'DATABASE_ERROR' | 'EXTERNAL_ID_REQUIRED' | 'TYPE_REQUIRED' | 'UNAUTHORIZED'>>;
 }
 /** `experiments` methods. Need an API key. */
 export interface C15tExperiments {
@@ -96,11 +106,11 @@ export interface C15tPublicClient {
      */
     manifest: (request?: C15tManifestRequest, options?: C15tCallOptions) => Promise<C15tResult<C15tManifestResult>>;
     readonly subjects: C15tPublicSubjects;
-    readonly consents: C15tConsents;
 }
 /** A client created with an API key. */
 export interface C15tClient extends C15tPublicClient {
     readonly subjects: C15tSubjects;
+    readonly consents: C15tConsents;
     readonly experiments: C15tExperiments;
     readonly legalDocuments: C15tLegalDocuments;
 }

package/dist-types/contract.d.ts

@@ -96,7 +96,7 @@ export type C15tCreateSubjectInput = PostSubjectInput extends infer Variant ? Va
 export type C15tIdentifySubjectInput = Omit<PatchSubjectFullInput, 'id'>;
 /** Input for `consents.check`. */
 export interface C15tCheckConsentInput<Types extends readonly ConsentPolicyType[]> {
-    /** Your user id, as linked with `subjects.identify`. */
+    /** Your user id, as linked with `subjects.identify` or a verified `identify()`. */
     readonly externalId: string;
     /** Policy types to report. Every one appears in `results`. */
     readonly types: Types;
@@ -150,7 +150,7 @@ export declare const endpoints: {
                 isLatestPolicy: boolean;
             };
         };
-    }, "DATABASE_ERROR" | "EXTERNAL_ID_REQUIRED" | "TYPE_REQUIRED">;
+    }, "DATABASE_ERROR" | "EXTERNAL_ID_REQUIRED" | "TYPE_REQUIRED" | "UNAUTHORIZED">;
     readonly createSubject: Endpoint<"/subjects", (Omit<{
         consentAction?: string | undefined;
         documentSnapshotToken?: string | undefined;
@@ -158,6 +158,7 @@ export declare const endpoints: {
         externalSubjectId?: string | undefined;
         givenAt: number;
         identityProvider?: string | undefined;
+        identityToken?: string | undefined;
         jurisdiction?: string | undefined;
         jurisdictionModel?: string | undefined;
         metadata?: {
@@ -244,6 +245,7 @@ export declare const endpoints: {
         externalSubjectId?: string | undefined;
         givenAt: number;
         identityProvider?: string | undefined;
+        identityToken?: string | undefined;
         jurisdiction?: string | undefined;
         jurisdictionModel?: string | undefined;
         metadata?: {
@@ -270,6 +272,7 @@ export declare const endpoints: {
         externalSubjectId?: string | undefined;
         givenAt: number;
         identityProvider?: string | undefined;
+        identityToken?: string | undefined;
         jurisdiction?: string | undefined;
         jurisdictionModel?: string | undefined;
         metadata?: {
@@ -462,7 +465,7 @@ export declare const endpoints: {
             id: string;
             identityProvider: string;
         };
-    }, "DATABASE_ERROR" | "EXTERNAL_ID_REQUIRED" | "NOT_FOUND">;
+    }, "DATABASE_ERROR" | "EXTERNAL_ID_REQUIRED" | "IDENTITY_CONFLICT" | "IDENTITY_TOKEN_INVALID" | "NOT_FOUND">;
     readonly init: Endpoint<"/init", C15tInitRequest | undefined, {
         branding: "c15t" | "consent" | "inth" | "none";
         cmpId?: number | undefined;
@@ -620,6 +623,7 @@ export declare const endpoints: {
             url: string;
             vendorListVersion: number;
         } | undefined;
+        hosting?: "inth" | "self-hosted" | undefined;
         location: {
             countryCode: string | null;
             regionCode: string | null;

package/dist-types/errors.d.ts

@@ -10,7 +10,7 @@
  *
  * Each method narrows this to the codes its endpoint can actually return.
  */
-export declare const C15T_API_ERROR_CODES: readonly ['BAD_REQUEST', 'CHOICE_OUT_OF_SCOPE', 'CHOICE_PREFERENCE_MISMATCH', 'CONFLICT', 'DATABASE_ERROR', 'EXTERNAL_ID_REQUIRED', 'INPUT_VALIDATION_FAILED', 'NOT_FOUND', 'POLICY_SNAPSHOT_EXPIRED', 'POLICY_SNAPSHOT_INVALID', 'POLICY_SNAPSHOT_REQUIRED', 'PURPOSE_NOT_ALLOWED', 'SERVICE_UNAVAILABLE', 'STALE_POLICY', 'SUBJECT_CONFLICT', 'TYPE_REQUIRED', 'UNAUTHORIZED'];
+export declare const C15T_API_ERROR_CODES: readonly ['BAD_REQUEST', 'CHOICE_OUT_OF_SCOPE', 'CHOICE_PREFERENCE_MISMATCH', 'CONFLICT', 'DATABASE_ERROR', 'EXTERNAL_ID_REQUIRED', 'IDENTITY_CONFLICT', 'IDENTITY_TOKEN_INVALID', 'INPUT_VALIDATION_FAILED', 'NOT_FOUND', 'POLICY_SNAPSHOT_EXPIRED', 'POLICY_SNAPSHOT_INVALID', 'POLICY_SNAPSHOT_REQUIRED', 'PURPOSE_NOT_ALLOWED', 'SERVICE_UNAVAILABLE', 'STALE_POLICY', 'SUBJECT_CONFLICT', 'TYPE_REQUIRED', 'UNAUTHORIZED'];
 /** A code the c15t backend can return. */
 export type C15tApiErrorCode = (typeof C15T_API_ERROR_CODES)[number];
 /**

package/dist-types/identity-token.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Mints identity tokens: signed proof, from your server, that a browser
+ * belongs to one of your users.
+ *
+ * The browser passes the token to `identify()`. The backend checks it with
+ * the same key (its `identityToken.signingKey` option) and only then counts
+ * the subject in `subjects.list` and `consents.check` for that user.
+ *
+ * HS256 over WebCrypto, so it runs in Node, Bun, Deno and edge runtimes
+ * without a JWT library.
+ */
+/** Options for {@link createIdentityToken}. */
+export interface C15tIdentityTokenOptions {
+    /**
+     * The secret shared with the backend's `identityToken.signingKey`, at
+     * least 32 bytes. Keep it on your server: anyone holding it can sign in as
+     * any user.
+     */
+    readonly signingKey: string;
+    /**
+     * How long the token is valid, in seconds. Mint a fresh one on each page
+     * load or sign-in rather than storing it.
+     *
+     * @default 3600
+     */
+    readonly ttlSeconds?: number;
+    /** `iss` claim. Must match the backend's `identityToken.issuer`. @default 'c15t' */
+    readonly issuer?: string;
+    /** `aud` claim. Must match the backend's `identityToken.audience`. @default 'c15t-identity' */
+    readonly audience?: string;
+    /** Clock, for tests. @default Date.now */
+    readonly now?: () => number;
+}
+/** The identity a token vouches for. */
+export interface C15tIdentityTokenUser {
+    /** Your user id. The same value the browser passes as `externalId`. */
+    readonly externalId: string;
+    /**
+     * Who issued the id, such as `clerk`. When set, the browser must send the
+     * same `identityProvider`.
+     */
+    readonly identityProvider?: string;
+}
+/**
+ * Signs an identity token for one of your users.
+ *
+ * Call it on your server after the visitor signs in, send the token to the
+ * page, and pass it to the browser client's `identify()` as
+ * `identityToken`.
+ *
+ * @param user - Your user id and, optionally, its identity provider.
+ * @param options - The shared signing key and token lifetime.
+ * @returns A compact JWT.
+ * @throws {TypeError} When `externalId` is empty, `signingKey` is shorter
+ * than 32 bytes, or `ttlSeconds` is not a positive integer.
+ *
+ * @example
+ * ```ts
+ * import { createIdentityToken } from '@c15t/node-sdk';
+ *
+ * const identityToken = await createIdentityToken(
+ *   { externalId: session.user.id },
+ *   { signingKey: process.env.C15T_IDENTITY_SIGNING_KEY! }
+ * );
+ * // In the browser:
+ * // await c15t.identify({ externalId: user.id, identityToken });
+ * ```
+ */
+export declare const createIdentityToken: (user: C15tIdentityTokenUser, options: C15tIdentityTokenOptions) => Promise<string>;

package/dist-types/index.d.ts

@@ -6,6 +6,8 @@
 export { createC15tClient } from './client.js';
 export type { C15tClient, C15tConsents, C15tExperiments, C15tLegalDocuments, C15tPublicClient, C15tPublicSubjects, C15tSubjects, } from './client.js';
 export type { C15tCheckConsentInput, C15tCheckConsentOutput, C15tCreateSubjectInput, C15tExperimentSummaryRequest, C15tGetSubjectRequest, C15tIdentifySubjectInput, C15tInitRequest, C15tManifestRequest, C15tManifestResult, C15tPublishLegalDocumentInput, } from './contract.js';
+export { createIdentityToken } from './identity-token.js';
+export type { C15tIdentityTokenOptions, C15tIdentityTokenUser, } from './identity-token.js';
 export { C15tConfigurationError } from './configuration-error.js';
 export type { C15tConfigurationIssue } from './configuration-error.js';
 export { C15T_API_ERROR_CODES, C15T_CLIENT_ERROR_CODES, C15tError, isC15tError, } from './errors.js';

package/dist-types/testing.d.ts

@@ -42,7 +42,7 @@ export type C15tMockCheckConsentHandler = (input: C15tCheckConsentInput<readonly
         readonly hasConsent: boolean;
         readonly isLatestPolicy: boolean;
     }>>;
-}, 'DATABASE_ERROR' | 'EXTERNAL_ID_REQUIRED' | 'TYPE_REQUIRED'>>;
+}, 'DATABASE_ERROR' | 'EXTERNAL_ID_REQUIRED' | 'TYPE_REQUIRED' | 'UNAUTHORIZED'>>;
 /** Handlers for {@link createMockC15tClient}. Any method can be left out. */
 export interface C15tMockHandlers {
     readonly status?: C15tMockHandler<C15tClient['status']>;

package/dist-types/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.0.0-alpha.5";
+export declare const version = "3.0.0-alpha.7";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@c15t/node-sdk",
-	"version": "3.0.0-alpha.5",
+	"version": "3.0.0-alpha.7",
 	"description": "Typed client for the c15t consent API: check consent, link users, record consents and publish legal documents from server code.",
 	"keywords": [
 		"c15t",
@@ -62,10 +62,10 @@
 		"test:watch": "bun prebuild && vitest"
 	},
 	"dependencies": {
-		"@c15t/schema": "3.0.0-alpha.4"
+		"@c15t/schema": "3.0.0-alpha.6"
 	},
 	"devDependencies": {
-		"@c15t/backend": "3.0.0-alpha.5",
+		"@c15t/backend": "3.0.0-alpha.7",
 		"@c15t/typescript-config": "0.0.1",
 		"@c15t/vitest-config": "1.0.0",
 		"@types/node": "25.5.0",