@catena/sdk 0.0.0-alpha-20260724191736

package/dist/client-G-8NfBx_.mjs

@@ -0,0 +1,597 @@
+import { p256KeypairFromPrivateKeyHex, p256PointFromCompressedHex, p256PublicKeyThumbprintFromPoint } from "./keypair.mjs";
+import { ApiKeyStamper } from "@turnkey/api-key-stamper";
+import * as v from "valibot";
+import { createHash, createPrivateKey, randomBytes, sign } from "node:crypto";
+//#region src/request-signing.ts
+const COVERED_COMPONENTS = "(\"@method\" \"@target-uri\" \"content-digest\" \"signature-agent\")";
+const ALGORITHM = "ecdsa-p256-sha256";
+const IDENTITY_URL = /^https?:\/\/[\x21\x23-\x7e]{1,255}$/;
+const NONCE = /^[\x21\x23-\x3a\x3c-\x7e]{1,128}$/;
+function agentKeyIdentityUrl(bankUrl, keyId) {
+	return `${bankUrl.replace(/\/+$/, "")}/agent-keys/${keyId}`;
+}
+function createAgentRequestSigner(options) {
+	const key = buildSignerKey(options.keypair);
+	const state = {
+		...key,
+		identityUrl: validatedIdentityUrl(options.identityUrl ?? agentKeyIdentityUrl(options.baseUrl, key.keyId))
+	};
+	return { sign: async (request) => {
+		const body = new Uint8Array(await request.clone().arrayBuffer());
+		const signatureHeaders = signRequest(state, {
+			method: request.method,
+			url: request.url,
+			body
+		}, {
+			nonce: randomBytes(16).toString("base64url"),
+			createdAt: new Date()
+		});
+		const headers = new Headers(request.headers);
+		for (const [name, value] of Object.entries(signatureHeaders)) headers.set(name, value);
+		return new Request(request, { headers });
+	} };
+}
+function buildSignerKey(keypair) {
+	const point = p256PointFromCompressedHex(keypair.publicKeyHex);
+	if (point === null) throw new Error("signer keypair has an invalid P-256 public key");
+	return {
+		signingKey: p256SigningKey(point, keypair.privateKeyHex),
+		keyId: p256PublicKeyThumbprintFromPoint(point)
+	};
+}
+function validatedIdentityUrl(identityUrl) {
+	if (!IDENTITY_URL.test(identityUrl)) throw new Error(`identity URL is outside the signature profile: "${identityUrl}"`);
+	return identityUrl;
+}
+function signRequest(state, request, params) {
+	if (!NONCE.test(params.nonce)) throw new Error("nonce is outside the signature profile");
+	const contentDigest = contentDigestHeader(request.body);
+	const signatureAgent = `"${state.identityUrl}"`;
+	const signatureParams = `${COVERED_COMPONENTS};created=${Math.floor(params.createdAt.getTime() / 1e3)};keyid="${state.keyId}";nonce="${params.nonce}";alg="${ALGORITHM}"`;
+	const signatureBase = [
+		`"@method": ${request.method.toUpperCase()}`,
+		`"@target-uri": ${canonicalTargetUri(new URL(request.url))}`,
+		`"content-digest": ${contentDigest}`,
+		`"signature-agent": ${signatureAgent}`,
+		`"@signature-params": ${signatureParams}`
+	].join("\n");
+	const signature = sign("sha256", Buffer.from(signatureBase, "utf8"), {
+		key: state.signingKey,
+		dsaEncoding: "ieee-p1363"
+	});
+	return {
+		"Content-Digest": contentDigest,
+		"Signature-Agent": signatureAgent,
+		"Signature-Input": `sig=${signatureParams}`,
+		Signature: `sig=:${signature.toString("base64")}:`
+	};
+}
+function contentDigestHeader(body) {
+	return `sha-256=:${createHash("sha256").update(body ?? "").digest("base64")}:`;
+}
+function canonicalTargetUri(url) {
+	return `${url.protocol}//${stripDefaultPort(url)}${url.pathname}${url.search}`;
+}
+function stripDefaultPort(url) {
+	const host = url.host.toLowerCase();
+	if (url.protocol === "https:" && url.port === "443" || url.protocol === "http:" && url.port === "80") return url.hostname.toLowerCase();
+	return host;
+}
+function p256SigningKey(point, privateKeyHex) {
+	return createPrivateKey({
+		key: {
+			kty: "EC",
+			crv: "P-256",
+			d: Buffer.from(privateKeyHex, "hex").toString("base64url"),
+			x: point.subarray(1, 33).toString("base64url"),
+			y: point.subarray(33, 65).toString("base64url")
+		},
+		format: "jwk"
+	});
+}
+//#endregion
+//#region package.json
+var version = "0.0.0-alpha-20260724191736";
+//#endregion
+//#region src/user-agent.ts
+const HTTP_TOKEN_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const AGENT_CLIENT_VERSION = version;
+function assertHttpToken(value, field) {
+	if (!HTTP_TOKEN_RE.test(value)) throw new Error(`${field} must be a valid HTTP token`);
+}
+function assertUaCommentSafe(value, field) {
+	let hasUnrepresentableCharacter = false;
+	for (let i = 0; i < value.length; i += 1) {
+		const code = value.charCodeAt(i);
+		if (code < 32 || code === 127 || code > 255) {
+			hasUnrepresentableCharacter = true;
+			break;
+		}
+	}
+	if (hasUnrepresentableCharacter || /[()\\]/.test(value)) throw new Error(`${field} must not contain parentheses, backslashes, control characters, or characters outside Latin-1`);
+}
+function buildUserAgent(appInfo) {
+	const sdkProduct = `catena-agent-client/${AGENT_CLIENT_VERSION}`;
+	if (!appInfo) return sdkProduct;
+	assertHttpToken(appInfo.name, "appInfo.name");
+	if (appInfo.version !== void 0) assertHttpToken(appInfo.version, "appInfo.version");
+	if (appInfo.url !== void 0) assertUaCommentSafe(appInfo.url, "appInfo.url");
+	const product = appInfo.version === void 0 ? appInfo.name : `${appInfo.name}/${appInfo.version}`;
+	return `${appInfo.url === void 0 ? product : `${product} (${appInfo.url})`} ${sdkProduct}`;
+}
+//#endregion
+//#region src/schemas.ts
+const moneyJsonSchema = v.object({
+	amount: v.string(),
+	asset_id: v.string()
+});
+const isoTimestampSchema = v.pipe(v.string(), v.isoTimestamp());
+const okSuccessResponseSchema = v.object({ success: v.literal(true) });
+const agentSchema = v.object({
+	id: v.string(),
+	name: v.string(),
+	status: v.string(),
+	organizationId: v.string(),
+	operatorEmail: v.nullable(v.string())
+});
+const whoamiResponseSchema = v.object({ agent: agentSchema });
+const policyRuleSchema = v.object({
+	id: v.string(),
+	ruleType: v.picklist([
+		"per_transaction_amount",
+		"daily_amount",
+		"weekly_amount",
+		"monthly_amount",
+		"hourly_count",
+		"daily_count"
+	]),
+	thresholdAmount: v.optional(moneyJsonSchema),
+	thresholdCount: v.optional(v.number()),
+	action: v.picklist(["block", "require_approval"]),
+	requiredApprovals: v.number(),
+	accountAggregationScope: v.picklist(["per_account", "across_accounts"]),
+	actorAggregationScope: v.picklist(["per_agent", "per_policy"]),
+	displayOrder: v.number()
+});
+const policyCapabilitySchema = v.object({
+	id: v.string(),
+	organizationId: v.string(),
+	policyId: v.string(),
+	capability: v.picklist([
+		"query_balance",
+		"read",
+		"send",
+		"transfer"
+	]),
+	accountId: v.string(),
+	rules: v.array(policyRuleSchema),
+	createdAt: isoTimestampSchema,
+	updatedAt: isoTimestampSchema
+});
+const counterpartyRulesSchema = v.object({
+	mode: v.picklist(["open", "restricted"]),
+	allowedCounterparties: v.optional(v.array(v.string())),
+	createAction: v.optional(v.picklist([
+		"allow",
+		"block",
+		"require_approval"
+	])),
+	allowCreate: v.optional(v.boolean())
+});
+const policySchema = v.object({
+	id: v.optional(v.string()),
+	description: v.optional(v.string()),
+	version: v.optional(v.number()),
+	name: v.string(),
+	capabilities: v.array(v.string()),
+	counterpartyRules: v.optional(counterpartyRulesSchema),
+	policyCapabilities: v.array(policyCapabilitySchema)
+});
+const policyResponseSchema = v.object({ policy: policySchema });
+const accountsResponseSchema = v.object({ accounts: v.array(v.object({
+	id: v.string(),
+	name: v.string(),
+	type: v.string(),
+	currency: v.string()
+})) });
+const accountBalanceResponseSchema = v.object({
+	accountId: v.string(),
+	balance: moneyJsonSchema,
+	balances: v.optional(v.object({
+		total: moneyJsonSchema,
+		available: moneyJsonSchema
+	}))
+});
+const accountTransactionSchema = v.object({
+	id: v.string(),
+	type: v.picklist([
+		"operator-send",
+		"operator-transfer",
+		"operator-deposit",
+		"operator-refund",
+		"microdeposit"
+	]),
+	action: v.optional(v.string()),
+	status: v.picklist([
+		"pending",
+		"processing",
+		"completed",
+		"failed",
+		"reversed"
+	]),
+	movementStatus: v.picklist([
+		"initiated",
+		"provider_pending",
+		"processing",
+		"completed",
+		"failed",
+		"reversed",
+		"manual_review"
+	]),
+	direction: v.picklist(["incoming", "outgoing"]),
+	amount: moneyJsonSchema,
+	fee: moneyJsonSchema,
+	currency: v.string(),
+	counterpartyName: v.optional(v.string()),
+	method: v.optional(v.picklist([
+		"ach",
+		"wire",
+		"on-chain"
+	])),
+	memo: v.optional(v.string()),
+	description: v.optional(v.string()),
+	txHash: v.optional(v.string()),
+	createdAt: isoTimestampSchema,
+	completedAt: v.optional(isoTimestampSchema)
+});
+const accountTransactionsResponseSchema = v.object({
+	accountId: v.string(),
+	transactions: v.array(accountTransactionSchema),
+	total: v.number()
+});
+const accountDepositAddressResponseSchema = v.object({
+	accountId: v.string(),
+	address: v.string(),
+	liquidationAddressId: v.optional(v.string()),
+	source: v.picklist(["wallet", "liquidation"])
+});
+const counterpartySchema = v.object({
+	id: v.string(),
+	name: v.string(),
+	rails: v.array(v.object({
+		id: v.string(),
+		type: v.string(),
+		walletAddress: v.optional(v.string()),
+		network: v.optional(v.string()),
+		bankName: v.optional(v.string()),
+		accountNumber: v.optional(v.string())
+	}))
+});
+const counterpartiesResponseSchema = v.object({ counterparties: v.array(counterpartySchema) });
+const intentStatusSchema = v.picklist([
+	"pending",
+	"processing",
+	"completed",
+	"blocked",
+	"failed"
+]);
+const intentNextActionSchema = v.object({
+	type: v.literal("submit_stamp"),
+	signingRequestId: v.string(),
+	signer: v.object({
+		algorithm: v.literal("p256"),
+		publicKeyHex: v.string()
+	}),
+	preparedBody: v.object({
+		body: v.string(),
+		bodyHash: v.string(),
+		expiresAt: isoTimestampSchema,
+		prepareToken: v.string()
+	})
+});
+const wireIntentResultSchema = v.object({
+	id: v.string(),
+	type: v.picklist([
+		"send",
+		"transfer",
+		"wallet_send",
+		"create_counterparty",
+		"x402"
+	]),
+	status: intentStatusSchema,
+	reasons: v.array(v.string()),
+	expiresAt: v.optional(v.nullable(isoTimestampSchema), null),
+	data: v.optional(v.nullable(v.record(v.string(), v.unknown())), null),
+	metadata: v.optional(v.object({ dataUrl: v.nullable(v.string()) })),
+	nextAction: v.optional(intentNextActionSchema)
+});
+function toIntentResult(wire) {
+	const { nextAction: _nextAction, ...intent } = wire;
+	return intent;
+}
+const SEND_METHODS = [
+	"ach",
+	"wire",
+	"on-chain"
+];
+const sendMethodSchema = v.picklist(SEND_METHODS);
+const sendActionSchema = v.object({
+	type: v.literal("send"),
+	accountId: v.string(),
+	counterpartyRailId: v.string(),
+	amount: v.string(),
+	method: sendMethodSchema,
+	memo: v.optional(v.string()),
+	description: v.optional(v.string())
+});
+const transferActionSchema = v.object({
+	type: v.literal("transfer"),
+	accountId: v.string(),
+	toAccountId: v.string(),
+	amount: v.string(),
+	memo: v.optional(v.string()),
+	description: v.optional(v.string())
+});
+const createCounterpartyActionSchema = v.object({
+	type: v.literal("create_counterparty"),
+	name: v.string(),
+	email: v.optional(v.string()),
+	rail: v.unknown()
+});
+const x402PaymentRequirementsSchema = v.looseObject({
+	scheme: v.string(),
+	network: v.string(),
+	asset: v.string(),
+	amount: v.string(),
+	payTo: v.string(),
+	maxTimeoutSeconds: v.number()
+});
+const x402ResourceSchema = v.looseObject({
+	url: v.string(),
+	serviceName: v.fallback(v.optional(v.pipe(v.string(), v.maxLength(255))), void 0)
+});
+const x402ActionSchema = v.object({
+	type: v.literal("x402"),
+	accountId: v.string(),
+	paymentRequirements: x402PaymentRequirementsSchema,
+	resource: v.optional(x402ResourceSchema)
+});
+v.variant("type", [
+	sendActionSchema,
+	transferActionSchema,
+	createCounterpartyActionSchema,
+	x402ActionSchema
+]);
+function toWireAction(action) {
+	if (action.type === "send" || action.type === "transfer") return {
+		...action,
+		amount: {
+			amount: action.amount,
+			asset_id: "USD"
+		}
+	};
+	return action;
+}
+const submitStampResponseSchema = v.object({ intent: wireIntentResultSchema });
+//#endregion
+//#region src/client.ts
+var ApiError = class extends Error {
+	status;
+	code;
+	constructor(status, message, code) {
+		super(code ? `API error ${status} [${code}]: ${message}` : `API error ${status}: ${message}`);
+		this.name = "ApiError";
+		this.status = status;
+		this.code = code;
+	}
+};
+const errorBodySchema = v.object({
+	error: v.nullish(v.string()),
+	message: v.nullish(v.string()),
+	code: v.nullish(v.string())
+});
+async function apiErrorFromResponse(res) {
+	const parsed = v.safeParse(errorBodySchema, await res.json().catch(() => void 0));
+	const body = parsed.success ? parsed.output : {};
+	if (body.error != null && body.message != null) return new ApiError(res.status, body.message, body.code ?? body.error);
+	return new ApiError(res.status, body.error ?? body.message ?? res.statusText, body.code ?? void 0);
+}
+async function parseApiResponse(res, schema) {
+	if (!res.ok) throw await apiErrorFromResponse(res);
+	return v.parse(schema, await res.json());
+}
+var IntentSubmitError = class extends Error {
+	intentId;
+	outcome;
+	constructor(params) {
+		const detail = params.cause instanceof Error ? params.cause.message : String(params.cause);
+		super(params.outcome === "not-submitted" ? `Intent ${params.intentId} was created but never submitted; no money moved: ${detail}` : `Intent ${params.intentId} submission could not be confirmed: ${detail}; poll getIntent("${params.intentId}") to a terminal status and resubmit only after blocked or failed`, { cause: params.cause });
+		this.name = "IntentSubmitError";
+		this.intentId = params.intentId;
+		this.outcome = params.outcome;
+	}
+};
+const DEFAULT_BASE_URL = "https://api.catena.com";
+var CatenaClient = class {
+	#baseUrl;
+	#userAgent;
+	#defaultHeaders;
+	#keypair;
+	#signer;
+	#fetch;
+	constructor(opts) {
+		this.#baseUrl = opts.baseUrl ?? DEFAULT_BASE_URL;
+		this.#userAgent = buildUserAgent(opts.appInfo);
+		this.#defaultHeaders = opts.defaultHeaders ?? {};
+		this.#keypair = p256KeypairFromPrivateKeyHex(opts.privateKeyHex);
+		this.#fetch = (opts.fetch ?? globalThis.fetch).bind(globalThis);
+		this.#signer = createAgentRequestSigner({
+			keypair: this.#keypair,
+			baseUrl: this.#baseUrl,
+			identityUrl: opts.identityUrl
+		});
+	}
+	#buildRequestHeaders(requestHeaders) {
+		const headers = new Headers({ "Content-Type": "application/json" });
+		for (const [name, value] of Object.entries(this.#defaultHeaders)) headers.set(name, value);
+		for (const [name, value] of Object.entries(requestHeaders ?? {})) headers.set(name, value);
+		headers.set("User-Agent", this.#userAgent);
+		headers.delete("Authorization");
+		return headers;
+	}
+	async #signedRequest(options) {
+		const url = new URL(`${this.#baseUrl}/v1/agent-api${options.path}`);
+		for (const [key, value] of Object.entries(options.query ?? {})) if (value !== void 0) url.searchParams.set(key, value);
+		const request = new Request(url, {
+			method: options.method,
+			headers: this.#buildRequestHeaders(options.headers),
+			body: options.body !== void 0 ? JSON.stringify(options.body) : null
+		});
+		return this.#signer.sign(request);
+	}
+	async #request(options, schema) {
+		return parseApiResponse(await this.#fetch(await this.#signedRequest(options)), schema);
+	}
+	async whoami() {
+		return (await this.#request({
+			method: "GET",
+			path: "/me"
+		}, whoamiResponseSchema)).agent;
+	}
+	async submitFeedback(body) {
+		await this.#request({
+			method: "POST",
+			path: "/feedback",
+			body: { body }
+		}, okSuccessResponseSchema);
+	}
+	async getPolicy() {
+		return (await this.#request({
+			method: "GET",
+			path: "/policy"
+		}, policyResponseSchema)).policy;
+	}
+	async listAccounts() {
+		return this.#request({
+			method: "GET",
+			path: "/accounts"
+		}, accountsResponseSchema);
+	}
+	async getAccountBalance(accountId) {
+		return this.#request({
+			method: "GET",
+			path: `/accounts/${encodeURIComponent(accountId)}/balance`
+		}, accountBalanceResponseSchema);
+	}
+	async listAccountTransactions(accountId, params = {}) {
+		return this.#request({
+			method: "GET",
+			path: `/accounts/${encodeURIComponent(accountId)}/transactions`,
+			query: {
+				start: params.start,
+				end: params.end,
+				limit: params.limit?.toString(),
+				offset: params.offset?.toString()
+			}
+		}, accountTransactionsResponseSchema);
+	}
+	async getAccountDepositAddress(accountId, params) {
+		return this.#request({
+			method: "GET",
+			path: `/accounts/${encodeURIComponent(accountId)}/deposit-address`,
+			query: {
+				network: params.network,
+				asset: params.asset
+			}
+		}, accountDepositAddressResponseSchema);
+	}
+	async listCounterparties(params = {}) {
+		return this.#request({
+			method: "GET",
+			path: "/counterparties",
+			query: {
+				address: params.address,
+				network: params.network
+			}
+		}, counterpartiesResponseSchema);
+	}
+	async submitIntent(params) {
+		const created = await this.#createIntentRaw(params);
+		const nextAction = created.nextAction;
+		if (!nextAction) return toIntentResult(created);
+		let submitRequest;
+		try {
+			const stamp = await this.#stampNextAction(nextAction);
+			submitRequest = await this.#signedRequest({
+				method: "POST",
+				path: `/intents/${encodeURIComponent(created.id)}/submit-stamp`,
+				body: {
+					preparedBody: nextAction.preparedBody,
+					stamp
+				}
+			});
+		} catch (cause) {
+			throw new IntentSubmitError({
+				intentId: created.id,
+				outcome: "not-submitted",
+				cause
+			});
+		}
+		try {
+			return await this.#submitStamp(submitRequest);
+		} catch (cause) {
+			throw new IntentSubmitError({
+				intentId: created.id,
+				outcome: "unknown",
+				cause
+			});
+		}
+	}
+	async #createIntentRaw(params) {
+		return this.#request({
+			method: "POST",
+			path: "/intents",
+			body: { action: toWireAction(params.action) },
+			...params.idempotencyKey !== void 0 && { headers: { "Idempotency-Key": params.idempotencyKey } }
+		}, wireIntentResultSchema);
+	}
+	async #stampNextAction(nextAction) {
+		if (nextAction.signer.publicKeyHex.toLowerCase() !== this.#keypair.publicKeyHex.toLowerCase()) throw new Error(`Local signer public key does not match requested signer ${nextAction.signer.publicKeyHex}; linked credential has ${this.#keypair.publicKeyHex}`);
+		const stamp = await new ApiKeyStamper({
+			apiPublicKey: this.#keypair.publicKeyHex,
+			apiPrivateKey: this.#keypair.privateKeyHex
+		}).stamp(nextAction.preparedBody.body);
+		return {
+			publicKeyHex: this.#keypair.publicKeyHex,
+			stampHeaderName: stamp.stampHeaderName,
+			stampHeaderValue: stamp.stampHeaderValue
+		};
+	}
+	async #submitStamp(request) {
+		return toIntentResult((await parseApiResponse(await this.#fetch(request), submitStampResponseSchema)).intent);
+	}
+	async getIntent(id) {
+		return toIntentResult(await this.#request({
+			method: "GET",
+			path: `/intents/${encodeURIComponent(id)}`
+		}, wireIntentResultSchema));
+	}
+	async unlinkAgent() {
+		await this.#request({
+			method: "POST",
+			path: "/unlink"
+		}, okSuccessResponseSchema);
+	}
+	async reportSettlement(params) {
+		await this.#request({
+			method: "POST",
+			path: `/intents/${encodeURIComponent(params.intentId)}/settlement-report`,
+			body: { txHash: params.txHash }
+		}, okSuccessResponseSchema);
+	}
+};
+function createCatenaClient(options) {
+	return new CatenaClient(options);
+}
+//#endregion
+export { x402PaymentRequirementsSchema as a, SEND_METHODS as i, IntentSubmitError as n, x402ResourceSchema as o, createCatenaClient as r, ApiError as t };

package/dist/client.d.mts

@@ -0,0 +1,2 @@
+import { C as SendMethod, E as AppInfo, S as SEND_METHODS, T as X402Resource, _ as IntentAction, a as IntentSubmitError, b as OnchainNetworkInput, c as AccountDepositAddressParams, d as AccountTransactionsResponse, f as AccountsResponse, g as Counterparty, h as CounterpartiesResponse, i as FetchLike, l as AccountDepositAddressResponse, m as CounterpartiesParams, n as CatenaClient, o as createCatenaClient, p as Agent, r as CatenaClientOptions, s as AccountBalanceResponse, t as ApiError, u as AccountTransactionsParams, v as IntentResult, w as X402PaymentRequirements, x as Policy, y as OnchainAssetInput } from "./client-DZHdFs_y.mjs";
+export { type AccountBalanceResponse, type AccountDepositAddressParams, type AccountDepositAddressResponse, type AccountTransactionsParams, type AccountTransactionsResponse, type AccountsResponse, type Agent, ApiError, type AppInfo, type CatenaClient, CatenaClientOptions, type CounterpartiesParams, type CounterpartiesResponse, type Counterparty, FetchLike, type IntentAction, type IntentResult, IntentSubmitError, type OnchainAssetInput, type OnchainNetworkInput, type Policy, SEND_METHODS, type SendMethod, type X402PaymentRequirements, type X402Resource, createCatenaClient };

package/dist/client.mjs

@@ -0,0 +1,2 @@
+import { i as SEND_METHODS, n as IntentSubmitError, r as createCatenaClient, t as ApiError } from "./client-G-8NfBx_.mjs";
+export { ApiError, IntentSubmitError, SEND_METHODS, createCatenaClient };

package/dist/keypair.d.mts

@@ -0,0 +1,29 @@
+//#region src/keypair.d.ts
+interface P256Keypair {
+  algorithm: "p256";
+  privateKeyHex: string;
+  publicKeyHex: string;
+}
+/**
+ * Generate a fresh agent credential. Feed `privateKeyHex` to
+ * `createCatenaClient`; the public half (or its thumbprint) is what gets
+ * registered with Catena when the agent is linked. The SDK never persists
+ * keys — storage is the caller's responsibility.
+ */
+declare function generateP256Keypair(): P256Keypair;
+/**
+ * Derive the full keypair from the private scalar alone, so a corrupt key
+ * throws at construction instead of surfacing as bank-side invalid_signature
+ * 401s — and a mismatched pair cannot exist at all.
+ */
+declare function p256KeypairFromPrivateKeyHex(privateKeyHex: string): P256Keypair;
+declare function p256PointFromCompressedHex(publicKeyHex: string): Buffer | null;
+/**
+ * RFC 7638 JWK thumbprint of a P-256 public key — the stable id the API
+ * knows a linked credential by. Returns null when the input is not a valid
+ * P-256 point.
+ */
+declare function computeP256PublicKeyThumbprint(publicKeyHex: string): string | null;
+declare function p256PublicKeyThumbprintFromPoint(point: Buffer): string;
+//#endregion
+export { P256Keypair, computeP256PublicKeyThumbprint, generateP256Keypair, p256KeypairFromPrivateKeyHex, p256PointFromCompressedHex, p256PublicKeyThumbprintFromPoint };

package/dist/keypair.mjs

@@ -0,0 +1,43 @@
+import { ECDH, createECDH, createHash } from "node:crypto";
+//#region src/keypair.ts
+function generateP256Keypair() {
+	const ecdh = createECDH("prime256v1");
+	ecdh.generateKeys();
+	return p256KeypairFromPrivateKeyHex(ecdh.getPrivateKey().toString("hex").padStart(64, "0"));
+}
+const PRIVATE_KEY_HEX = /^[0-9a-f]{64}$/i;
+function p256KeypairFromPrivateKeyHex(privateKeyHex) {
+	if (!PRIVATE_KEY_HEX.test(privateKeyHex)) throw new Error("P-256 private key must be 64 hex characters");
+	const normalized = privateKeyHex.toLowerCase();
+	const ecdh = createECDH("prime256v1");
+	try {
+		ecdh.setPrivateKey(Buffer.from(normalized, "hex"));
+	} catch {
+		throw new Error("value is not a valid P-256 private key (scalar out of range)");
+	}
+	return {
+		algorithm: "p256",
+		privateKeyHex: normalized,
+		publicKeyHex: ecdh.getPublicKey("hex", "compressed")
+	};
+}
+function p256PointFromCompressedHex(publicKeyHex) {
+	try {
+		const uncompressed = ECDH.convertKey(publicKeyHex, "prime256v1", "hex", "hex", "uncompressed");
+		const point = Buffer.isBuffer(uncompressed) ? uncompressed : Buffer.from(uncompressed, "hex");
+		return point.length === 65 ? point : null;
+	} catch {
+		return null;
+	}
+}
+function computeP256PublicKeyThumbprint(publicKeyHex) {
+	const point = p256PointFromCompressedHex(publicKeyHex);
+	return point === null ? null : p256PublicKeyThumbprintFromPoint(point);
+}
+function p256PublicKeyThumbprintFromPoint(point) {
+	const x = point.subarray(1, 33).toString("base64url");
+	const y = point.subarray(33, 65).toString("base64url");
+	return createHash("sha256").update(`{"crv":"P-256","kty":"EC","x":"${x}","y":"${y}"}`, "utf8").digest("base64url");
+}
+//#endregion
+export { computeP256PublicKeyThumbprint, generateP256Keypair, p256KeypairFromPrivateKeyHex, p256PointFromCompressedHex, p256PublicKeyThumbprintFromPoint };