@atcute/oauth-crypto 0.1.0

package/lib/dpop/verify.ts

@@ -0,0 +1,169 @@
+import { fromBase64Url } from '@atcute/multibase';
+import { decodeUtf8From } from '@atcute/uint8array';
+
+import * as v from '@badrap/valita';
+
+import { getImportAlgorithm } from '../internal/crypto.js';
+import { computeJktFromJwk } from '../jwk/compute-jkt.js';
+import type { PublicJwk, SigningAlgorithm } from '../jwk/types.js';
+import { verifyJwt } from '../jwt/index.js';
+
+import type { Awaitable } from './types.js';
+
+const dpopJwkSchema = v.union(
+	v.object({
+		kty: v.literal('EC'),
+		crv: v.union(v.literal('P-256'), v.literal('P-384'), v.literal('P-521')),
+		x: v.string(),
+		y: v.string(),
+	}),
+	v.object({
+		kty: v.literal('RSA'),
+		e: v.string(),
+		n: v.string(),
+	}),
+);
+
+const dpopHeaderSchema = v.object({
+	typ: v.literal('dpop+jwt'),
+	alg: v.string().assert((alg) => alg !== 'none', 'alg must not be "none"'),
+	jwk: dpopJwkSchema,
+});
+
+const dpopPayloadSchema = v.object({
+	htm: v.string(),
+	htu: v.string(),
+	iat: v.number(),
+	jti: v.string(),
+	nonce: v.string().optional(),
+});
+
+export type DpopClaims = v.Infer<typeof dpopPayloadSchema>;
+type DpopJwk = v.Infer<typeof dpopJwkSchema>;
+
+export interface DpopVerifyResult {
+	claims: DpopClaims;
+	jkt: string;
+	jwk: PublicJwk;
+}
+
+export interface DpopVerifyOptions {
+	method: string;
+	url: string;
+	nonce?: { check(nonce: string): Awaitable<boolean> };
+	maxClockSkew?: number;
+}
+
+/**
+ * error thrown when dpop verification fails.
+ */
+export class DpopVerifyError extends Error {
+	constructor(
+		message: string,
+		public code: 'missing' | 'invalid' | 'expired' | 'nonce_required',
+	) {
+		super(message);
+		this.name = 'DpopVerifyError';
+	}
+}
+
+/**
+ * verifies a dpop proof from a request header.
+ *
+ * @param dpopHeader dpop header value
+ * @param options verification options
+ * @returns verification result with claims and jwk thumbprint
+ * @throws {DpopVerifyError} if verification fails
+ */
+export const verifyDpopProof = async (
+	dpopHeader: string | null | undefined,
+	options: DpopVerifyOptions,
+): Promise<DpopVerifyResult> => {
+	if (!dpopHeader) {
+		throw new DpopVerifyError(`missing dpop header`, 'missing');
+	}
+
+	const { method, url, nonce: dpopNonce, maxClockSkew = 60 } = options;
+	const parts = dpopHeader.split('.');
+	if (parts.length !== 3) {
+		throw new DpopVerifyError(`invalid dpop proof format`, 'invalid');
+	}
+
+	let header: v.Infer<typeof dpopHeaderSchema>;
+	try {
+		header = dpopHeaderSchema.parse(decodeSegment(parts[0]), { mode: 'passthrough' });
+	} catch {
+		throw new DpopVerifyError(`invalid dpop header`, 'invalid');
+	}
+
+	const { jwk, alg } = header;
+	if (!isSigningAlgorithm(alg)) {
+		throw new DpopVerifyError(`unsupported dpop alg`, 'invalid');
+	}
+
+	let payload: DpopClaims;
+	try {
+		const key = await importPublicKey(jwk, alg);
+		const raw = await verifyJwt(dpopHeader, { key, alg, typ: 'dpop+jwt' });
+		payload = dpopPayloadSchema.parse(raw, { mode: 'passthrough' });
+	} catch (err) {
+		if (err instanceof v.ValitaError) {
+			throw new DpopVerifyError(`invalid dpop payload`, 'invalid');
+		}
+		throw new DpopVerifyError(`dpop signature verification failed`, 'invalid');
+	}
+
+	if (payload.htm !== method) {
+		throw new DpopVerifyError(`dpop htm mismatch: expected ${method}, got ${payload.htm}`, 'invalid');
+	}
+	if (payload.htu !== url) {
+		throw new DpopVerifyError(`dpop htu mismatch: expected ${url}, got ${payload.htu}`, 'invalid');
+	}
+
+	const now = Math.floor(Date.now() / 1000);
+	if (payload.iat > now + maxClockSkew) {
+		throw new DpopVerifyError(`dpop proof issued in the future`, 'invalid');
+	}
+	if (payload.iat < now - maxClockSkew) {
+		throw new DpopVerifyError(`dpop proof expired`, 'expired');
+	}
+
+	if (dpopNonce) {
+		if (!payload.nonce || !(await dpopNonce.check(payload.nonce))) {
+			throw new DpopVerifyError(`invalid or missing dpop nonce`, 'nonce_required');
+		}
+	}
+
+	const jkt = await computeJktFromJwk(jwk as PublicJwk);
+
+	return { claims: payload, jwk: jwk as DpopJwk, jkt };
+};
+
+const importPublicKey = async (jwk: PublicJwk, alg: SigningAlgorithm): Promise<CryptoKey> => {
+	const algorithm = getImportAlgorithm(alg, jwk.kty === 'EC' ? jwk.crv : undefined);
+	const key = await crypto.subtle.importKey('jwk', jwk, algorithm, true, ['verify']);
+	if (!(key instanceof CryptoKey)) {
+		throw new Error(`expected asymmetric key, got symmetric`);
+	}
+
+	return key;
+};
+
+const isSigningAlgorithm = (alg: string): alg is SigningAlgorithm => {
+	return (
+		alg === 'ES256' ||
+		alg === 'ES384' ||
+		alg === 'ES512' ||
+		alg === 'PS256' ||
+		alg === 'PS384' ||
+		alg === 'PS512' ||
+		alg === 'RS256' ||
+		alg === 'RS384' ||
+		alg === 'RS512'
+	);
+};
+
+const decodeSegment = (segment: string): unknown => {
+	const bytes = fromBase64Url(segment);
+	return JSON.parse(decodeUtf8From(bytes));
+};

package/lib/hash/index.ts

@@ -0,0 +1,2 @@
+export { generatePkce } from './pkce.js';
+export { sha256Base64Url } from './sha256.js';

package/lib/hash/pkce.ts

@@ -0,0 +1,18 @@
+import { nanoid } from 'nanoid';
+
+import { sha256Base64Url } from './sha256.js';
+
+/**
+ * generates pkce verifier and challenge (s256).
+ *
+ * @param length verifier length (43-128 per rfc 7636)
+ * @returns pkce values
+ */
+export const generatePkce = async (
+	length = 64,
+): Promise<{ verifier: string; challenge: string; method: 'S256' }> => {
+	const verifier = nanoid(length);
+	const challenge = await sha256Base64Url(verifier);
+
+	return { verifier, challenge, method: 'S256' };
+};

package/lib/hash/sha256.ts

@@ -0,0 +1,14 @@
+import { toBase64Url } from '@atcute/multibase';
+import { encodeUtf8, toSha256 } from '@atcute/uint8array';
+
+/**
+ * computes sha-256 hash and returns base64url-encoded result.
+ *
+ * @param input string to hash
+ * @returns base64url-encoded sha-256 hash
+ */
+export const sha256Base64Url = async (input: string): Promise<string> => {
+	const bytes = encodeUtf8(input);
+	const digest = await toSha256(bytes);
+	return toBase64Url(digest);
+};

package/lib/index.ts

@@ -0,0 +1,5 @@
+export * from './client-assertion/index.js';
+export * from './dpop/index.js';
+export * from './hash/index.js';
+export * from './jwk/index.js';
+export * from './jwt/index.js';

package/lib/internal/crypto.ts

@@ -0,0 +1,92 @@
+import type { SigningAlgorithm } from '../jwk/types.js';
+
+const HASH_BY_ALG: Record<SigningAlgorithm, 'SHA-256' | 'SHA-384' | 'SHA-512'> = {
+	ES256: 'SHA-256',
+	ES384: 'SHA-384',
+	ES512: 'SHA-512',
+	PS256: 'SHA-256',
+	PS384: 'SHA-384',
+	PS512: 'SHA-512',
+	RS256: 'SHA-256',
+	RS384: 'SHA-384',
+	RS512: 'SHA-512',
+};
+
+const CURVE_BY_ALG: Record<SigningAlgorithm, 'P-256' | 'P-384' | 'P-521' | null> = {
+	ES256: 'P-256',
+	ES384: 'P-384',
+	ES512: 'P-521',
+	PS256: null,
+	PS384: null,
+	PS512: null,
+	RS256: null,
+	RS384: null,
+	RS512: null,
+};
+
+export const getHashName = (alg: SigningAlgorithm): 'SHA-256' | 'SHA-384' | 'SHA-512' => {
+	return HASH_BY_ALG[alg];
+};
+
+export const getNamedCurve = (alg: SigningAlgorithm): 'P-256' | 'P-384' | 'P-521' | null => {
+	return CURVE_BY_ALG[alg];
+};
+
+export const getSignAlgorithm = (alg: SigningAlgorithm): AlgorithmIdentifier | EcdsaParams | RsaPssParams => {
+	if (alg.startsWith('ES')) {
+		return { name: 'ECDSA', hash: { name: getHashName(alg) } };
+	}
+	if (alg.startsWith('PS')) {
+		return {
+			name: 'RSA-PSS',
+			hash: { name: getHashName(alg) },
+			saltLength: getHashLength(getHashName(alg)),
+		};
+	}
+	return { name: 'RSASSA-PKCS1-v1_5' };
+};
+
+export const getImportAlgorithm = (
+	alg: SigningAlgorithm,
+	curve?: 'P-256' | 'P-384' | 'P-521',
+): EcKeyImportParams | RsaHashedImportParams => {
+	if (alg.startsWith('ES')) {
+		const namedCurve = curve ?? getNamedCurve(alg);
+		if (!namedCurve) {
+			throw new Error(`unable to determine curve for ${alg}`);
+		}
+		return { name: 'ECDSA', namedCurve };
+	}
+
+	if (alg.startsWith('PS')) {
+		return { name: 'RSA-PSS', hash: { name: getHashName(alg) } };
+	}
+
+	return { name: 'RSASSA-PKCS1-v1_5', hash: { name: getHashName(alg) } };
+};
+
+export const getGenerateAlgorithm = (alg: SigningAlgorithm): EcKeyGenParams | RsaHashedKeyGenParams => {
+	const curve = getNamedCurve(alg);
+	if (curve) {
+		return { name: 'ECDSA', namedCurve: curve };
+	}
+
+	const hash = { name: getHashName(alg) };
+	return {
+		name: alg.startsWith('PS') ? 'RSA-PSS' : 'RSASSA-PKCS1-v1_5',
+		hash,
+		modulusLength: 2048,
+		publicExponent: new Uint8Array([0x01, 0x00, 0x01]),
+	};
+};
+
+const getHashLength = (hash: 'SHA-256' | 'SHA-384' | 'SHA-512'): number => {
+	switch (hash) {
+		case 'SHA-256':
+			return 32;
+		case 'SHA-384':
+			return 48;
+		case 'SHA-512':
+			return 64;
+	}
+};

package/lib/internal/jwk.ts

@@ -0,0 +1,157 @@
+import { fromBase64Pad, toBase64Pad } from '@atcute/multibase';
+
+import type { PrivateJwk, PublicJwk, SigningAlgorithm } from '../jwk/types.js';
+
+import { getImportAlgorithm } from './crypto.js';
+
+const SIGNING_ALGORITHMS: readonly SigningAlgorithm[] = [
+	'ES256',
+	'ES384',
+	'ES512',
+	'PS256',
+	'PS384',
+	'PS512',
+	'RS256',
+	'RS384',
+	'RS512',
+];
+
+const CURVE_TO_ALG: Record<string, SigningAlgorithm> = {
+	'P-256': 'ES256',
+	'P-384': 'ES384',
+	'P-521': 'ES512',
+};
+
+export const isSigningAlgorithm = (alg: string): alg is SigningAlgorithm => {
+	return (SIGNING_ALGORITHMS as readonly string[]).includes(alg);
+};
+
+export const parsePrivateJwkInput = (input: PrivateJwk | string): PrivateJwk => {
+	if (typeof input === 'string') {
+		try {
+			const jwk = JSON.parse(input) as PrivateJwk;
+			return jwk;
+		} catch {
+			throw new Error(`invalid JSON string`);
+		}
+	}
+
+	if (typeof input === 'object' && input !== null && 'kty' in input) {
+		return input;
+	}
+
+	throw new Error(`invalid input: expected JWK object or JSON string`);
+};
+
+export const resolveSigningAlgorithm = (
+	jwk: PrivateJwk,
+	override?: SigningAlgorithm,
+): SigningAlgorithm | undefined => {
+	if (override) {
+		return override;
+	}
+
+	const alg = jwk.alg;
+	if (alg && isSigningAlgorithm(alg)) {
+		return alg;
+	}
+
+	if (jwk.kty === 'EC') {
+		const inferred = CURVE_TO_ALG[jwk.crv];
+		if (inferred) {
+			return inferred;
+		}
+	}
+
+	return undefined;
+};
+
+export const derivePublicJwk = (privateJwk: PrivateJwk, kid?: string, alg?: SigningAlgorithm): PublicJwk => {
+	if (privateJwk.kty === 'EC') {
+		const { crv, x, y } = privateJwk;
+		return { kty: 'EC', crv, x, y, kid, alg, use: 'sig' };
+	}
+
+	if (privateJwk.kty === 'RSA') {
+		const { n, e } = privateJwk;
+		return { kty: 'RSA', n, e, kid, alg, use: 'sig' };
+	}
+
+	throw new Error(`unsupported key type`);
+};
+
+export const importPrivateKeyFromJwk = async (jwk: PrivateJwk, alg: SigningAlgorithm): Promise<CryptoKey> => {
+	if (!('d' in jwk) || !jwk.d) {
+		throw new Error(`expected a private key (missing 'd' parameter)`);
+	}
+
+	if (jwk.kty === 'EC' && !alg.startsWith('ES')) {
+		throw new Error(`algorithm ${alg} does not match ec key`);
+	}
+	if (jwk.kty === 'RSA' && alg.startsWith('ES')) {
+		throw new Error(`algorithm ${alg} does not match rsa key`);
+	}
+
+	const algorithm = getImportAlgorithm(alg, jwk.kty === 'EC' ? jwk.crv : undefined);
+	const key = await crypto.subtle.importKey('jwk', jwk, algorithm, true, ['sign']);
+
+	if (!(key instanceof CryptoKey)) {
+		throw new Error(`expected asymmetric key, got symmetric`);
+	}
+
+	return key;
+};
+
+export const exportPrivateJwkFromKey = async (
+	key: CryptoKey,
+	alg: SigningAlgorithm,
+	kid?: string,
+): Promise<PrivateJwk> => {
+	const jwk = (await crypto.subtle.exportKey('jwk', key)) as PrivateJwk;
+	jwk.alg = alg;
+	if (kid) {
+		jwk.kid = kid;
+	}
+	return jwk;
+};
+
+export const importPkcs8PrivateKey = async (pem: string, alg: SigningAlgorithm): Promise<CryptoKey> => {
+	const bytes = parsePkcs8Pem(pem);
+	const algorithm = getImportAlgorithm(alg);
+
+	const key = await crypto.subtle.importKey('pkcs8', bytes, algorithm, true, ['sign']);
+
+	if (!(key instanceof CryptoKey)) {
+		throw new Error(`expected asymmetric key, got symmetric`);
+	}
+
+	return key;
+};
+
+export const exportPkcs8PrivateKey = async (key: CryptoKey): Promise<string> => {
+	const pkcs8 = await crypto.subtle.exportKey('pkcs8', key);
+	const bytes = new Uint8Array(pkcs8);
+	const base64 = toBase64Pad(bytes);
+
+	return ['-----BEGIN PRIVATE KEY-----', ...chunk64(base64), '-----END PRIVATE KEY-----', ''].join('\n');
+};
+
+const parsePkcs8Pem = (pem: string): ArrayBuffer => {
+	const match = pem.match(/-----BEGIN PRIVATE KEY-----([\s\S]*?)-----END PRIVATE KEY-----/);
+	if (!match) {
+		throw new Error(`invalid pkcs8 pem`);
+	}
+
+	const base64 = match[1].replace(/\s+/g, '');
+	const bytes = fromBase64Pad(base64);
+	const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+	return buffer;
+};
+
+const chunk64 = (input: string): string[] => {
+	const chunks: string[] = [];
+	for (let i = 0; i < input.length; i += 64) {
+		chunks.push(input.slice(i, i + 64));
+	}
+	return chunks;
+};

package/lib/internal/key-cache.ts

@@ -0,0 +1,51 @@
+import type { PrivateJwk, PublicJwk } from '../jwk/types.js';
+
+import { derivePublicJwk, importPrivateKeyFromJwk } from './jwk.js';
+
+/**
+ * cached key material for a JWK.
+ */
+export interface CachedKeyMaterial {
+	cryptoKey: CryptoKey;
+	publicJwk: PublicJwk;
+}
+
+/**
+ * cache for imported keys.
+ * uses WeakMap so entries are garbage collected when JWK objects are no longer referenced.
+ */
+const keyCache = new WeakMap<PrivateJwk, CachedKeyMaterial>();
+
+/**
+ * retrieves or creates cached key material for a JWK.
+ *
+ * @param jwk private JWK to get material for
+ * @returns cached key material (CryptoKey and derived public JWK)
+ */
+export const getCachedKeyMaterial = async (jwk: PrivateJwk): Promise<CachedKeyMaterial> => {
+	const cached = keyCache.get(jwk);
+	if (cached) {
+		return cached;
+	}
+
+	const { alg } = jwk;
+	const cryptoKey = await importPrivateKeyFromJwk(jwk, alg);
+	const publicJwk = derivePublicJwk(jwk, jwk.kid, alg);
+	const material: CachedKeyMaterial = { cryptoKey, publicJwk };
+
+	keyCache.set(jwk, material);
+
+	return material;
+};
+
+/**
+ * pre-populates the cache with already-imported key material.
+ * useful for PKCS8 imports where we already have the CryptoKey.
+ *
+ * @param jwk private JWK to cache for
+ * @param cryptoKey already-imported CryptoKey
+ */
+export const setCachedKeyMaterial = (jwk: PrivateJwk, cryptoKey: CryptoKey): void => {
+	const publicJwk = derivePublicJwk(jwk, jwk.kid, jwk.alg);
+	keyCache.set(jwk, { cryptoKey, publicJwk });
+};

package/lib/jwk/compute-jkt.ts

@@ -0,0 +1,27 @@
+import { toBase64Url } from '@atcute/multibase';
+import { encodeUtf8, toSha256 } from '@atcute/uint8array';
+
+import type { PublicJwk } from './types.js';
+
+/**
+ * computes the jwk thumbprint (rfc 7638) for a public key.
+ *
+ * @param jwk public jwk
+ * @returns base64url-encoded sha-256 thumbprint
+ */
+export const computeJktFromJwk = async (jwk: PublicJwk): Promise<string> => {
+	let canonical: Record<string, string>;
+
+	if (jwk.kty === 'EC') {
+		const { crv, x, y } = jwk;
+		canonical = { crv, kty: jwk.kty, x, y };
+	} else {
+		const { e, n } = jwk;
+		canonical = { e, kty: jwk.kty, n };
+	}
+
+	const serialized = JSON.stringify(canonical);
+	const hash = await toSha256(encodeUtf8(serialized));
+
+	return toBase64Url(hash);
+};

package/lib/jwk/index.ts

@@ -0,0 +1,12 @@
+export { computeJktFromJwk } from './compute-jkt.js';
+export { derivePublicJwk } from '../internal/jwk.js';
+export { exportPkcs8PrivateKey } from './keys.js';
+export type {
+	EcPrivateJwk,
+	EcPublicJwk,
+	PrivateJwk,
+	PublicJwk,
+	RsaPrivateJwk,
+	RsaPublicJwk,
+	SigningAlgorithm,
+} from './types.js';

package/lib/jwk/keys.ts

@@ -0,0 +1,15 @@
+import { exportPkcs8PrivateKey as exportPkcs8 } from '../internal/jwk.js';
+import { getCachedKeyMaterial } from '../internal/key-cache.js';
+
+import type { PrivateJwk } from './types.js';
+
+/**
+ * exports a private JWK to PKCS8 PEM format.
+ *
+ * @param jwk private JWK to export
+ * @returns PKCS8 PEM string
+ */
+export const exportPkcs8PrivateKey = async (jwk: PrivateJwk): Promise<string> => {
+	const { cryptoKey } = await getCachedKeyMaterial(jwk);
+	return exportPkcs8(cryptoKey);
+};

package/lib/jwk/types.ts

@@ -0,0 +1,51 @@
+/**
+ * signing algorithms supported by atproto oauth.
+ */
+export type SigningAlgorithm =
+	| 'ES256'
+	| 'ES384'
+	| 'ES512'
+	| 'PS256'
+	| 'PS384'
+	| 'PS512'
+	| 'RS256'
+	| 'RS384'
+	| 'RS512';
+
+export interface EcPublicJwk {
+	kty: 'EC';
+	crv: 'P-256' | 'P-384' | 'P-521';
+	x: string;
+	y: string;
+	alg?: SigningAlgorithm;
+	use?: 'sig';
+	kid?: string;
+}
+
+export interface RsaPublicJwk {
+	kty: 'RSA';
+	n: string;
+	e: string;
+	alg?: SigningAlgorithm;
+	use?: 'sig';
+	kid?: string;
+}
+
+export type PublicJwk = EcPublicJwk | RsaPublicJwk;
+
+export interface EcPrivateJwk extends EcPublicJwk {
+	alg: SigningAlgorithm;
+	d: string;
+}
+
+export interface RsaPrivateJwk extends RsaPublicJwk {
+	alg: SigningAlgorithm;
+	d: string;
+	p?: string;
+	q?: string;
+	dp?: string;
+	dq?: string;
+	qi?: string;
+}
+
+export type PrivateJwk = EcPrivateJwk | RsaPrivateJwk;