@apifuse/provider-sdk 2.1.0-beta.2 → 2.1.0-beta.21

package/src/ceremonies/index.ts

@@ -8,7 +8,12 @@ import {
 	TurnValidationError,
 	ValidationError,
 } from "../errors";
-import type { AuthFlowDefinition, AuthTurn, FlowContext } from "../types";
+import type {
+	AuthFlowDefinition,
+	AuthFlowInputHandler,
+	AuthTurn,
+	FlowContext,
+} from "../types";
 
 type TurnKind =
 	| "abort"
@@ -21,7 +26,7 @@ type TurnKind =
 	| "redirect"
 	| "retry";
 
-type CeremonyHandler = AuthFlowDefinition["start"];
+type CeremonyHandler = AuthFlowInputHandler;
 
 type JsonObject = Record<string, unknown>;
 
@@ -44,6 +49,7 @@ const authTurnSchema = {
 			additionalProperties: true,
 		},
 		hint: { type: "string" },
+		hintKey: { type: "string" },
 		timing: {
 			type: "object",
 			additionalProperties: false,

package/src/choice-token.ts

@@ -0,0 +1,165 @@
+import {
+	createCipheriv,
+	createDecipheriv,
+	createHash,
+	createHmac,
+	randomBytes,
+	timingSafeEqual,
+} from "node:crypto";
+
+export type ProviderChoiceTokenPayload = Record<string, unknown>;
+
+export type ProviderChoiceTokenErrorReason =
+	| "invalid_shape"
+	| "invalid_signature"
+	| "invalid_payload"
+	| "invalid_binding"
+	| "stale";
+
+export class ProviderChoiceTokenError extends Error {
+	readonly reason: ProviderChoiceTokenErrorReason;
+
+	constructor(reason: ProviderChoiceTokenErrorReason, message: string) {
+		super(message);
+		this.name = "ProviderChoiceTokenError";
+		this.reason = reason;
+	}
+}
+
+export interface CreateProviderChoiceTokenOptions<
+	TPayload extends ProviderChoiceTokenPayload,
+> {
+	prefix: string;
+	payload: TPayload;
+	secret: string;
+}
+
+export interface ParseProviderChoiceTokenOptions {
+	token: string;
+	prefix: string;
+	secret: string;
+}
+
+export interface FreshProviderChoiceIssuedAtOptions {
+	ttlMs: number;
+	nowMs?: number;
+	futureToleranceMs?: number;
+}
+
+export function createProviderChoiceToken<
+	TPayload extends ProviderChoiceTokenPayload,
+>(options: CreateProviderChoiceTokenOptions<TPayload>): string {
+	const iv = randomBytes(12);
+	const cipher = createCipheriv(
+		"aes-256-gcm",
+		choiceEncryptionKey(options.secret),
+		iv,
+	);
+	const encryptedPayload = Buffer.concat([
+		cipher.update(JSON.stringify(options.payload), "utf8"),
+		cipher.final(),
+	]).toString("base64url");
+	const authTag = cipher.getAuthTag().toString("base64url");
+	const encodedIv = iv.toString("base64url");
+	const signature = signProviderChoiceTokenBody(
+		`${options.prefix}.${encodedIv}.${encryptedPayload}.${authTag}`,
+		options.secret,
+	);
+	return `${options.prefix}.${encodedIv}.${encryptedPayload}.${authTag}.${signature}`;
+}
+
+export function parseProviderChoiceToken(
+	options: ParseProviderChoiceTokenOptions,
+): ProviderChoiceTokenPayload {
+	const [
+		actualPrefix,
+		encodedIv,
+		encryptedPayload,
+		authTag,
+		signature,
+		...extra
+	] = options.token.split(".");
+	if (
+		actualPrefix !== options.prefix ||
+		!encodedIv ||
+		!encryptedPayload ||
+		!authTag ||
+		!signature ||
+		extra.length > 0
+	) {
+		throw new ProviderChoiceTokenError(
+			"invalid_shape",
+			"Provider choice token shape is invalid.",
+		);
+	}
+
+	const signedBody = `${options.prefix}.${encodedIv}.${encryptedPayload}.${authTag}`;
+	const expectedSignature = signProviderChoiceTokenBody(
+		signedBody,
+		options.secret,
+	);
+	const actualBuffer = Buffer.from(signature);
+	const expectedBuffer = Buffer.from(expectedSignature);
+	if (
+		actualBuffer.length !== expectedBuffer.length ||
+		!timingSafeEqual(actualBuffer, expectedBuffer)
+	) {
+		throw new ProviderChoiceTokenError(
+			"invalid_signature",
+			"Provider choice token signature is invalid.",
+		);
+	}
+
+	try {
+		const decipher = createDecipheriv(
+			"aes-256-gcm",
+			choiceEncryptionKey(options.secret),
+			Buffer.from(encodedIv, "base64url"),
+		);
+		decipher.setAuthTag(Buffer.from(authTag, "base64url"));
+		const decrypted = Buffer.concat([
+			decipher.update(Buffer.from(encryptedPayload, "base64url")),
+			decipher.final(),
+		]).toString("utf8");
+		const parsed = JSON.parse(decrypted);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			throw new Error("payload is not an object");
+		}
+		return Object.fromEntries(Object.entries(parsed));
+	} catch {
+		throw new ProviderChoiceTokenError(
+			"invalid_payload",
+			"Provider choice token payload is invalid.",
+		);
+	}
+}
+
+export function assertFreshProviderChoiceIssuedAt(
+	issuedAtMs: unknown,
+	options: FreshProviderChoiceIssuedAtOptions,
+): number {
+	const parsed =
+		typeof issuedAtMs === "number" ? issuedAtMs : Number(issuedAtMs);
+	const nowMs = options.nowMs ?? Date.now();
+	const futureToleranceMs = options.futureToleranceMs ?? 30_000;
+	if (
+		!Number.isFinite(parsed) ||
+		parsed <= 0 ||
+		nowMs - parsed > options.ttlMs ||
+		parsed - nowMs > futureToleranceMs
+	) {
+		throw new ProviderChoiceTokenError(
+			"stale",
+			"Provider choice token is stale.",
+		);
+	}
+	return parsed;
+}
+
+function choiceEncryptionKey(secret: string): Buffer {
+	return createHash("sha256").update(secret).digest();
+}
+
+function signProviderChoiceTokenBody(body: string, secret: string): string {
+	return createHmac("sha256", secret).update(body).digest("base64url");
+}

package/src/cli/commands.ts

@@ -2,6 +2,8 @@ export type ApifuseCommandName =
 	| "create"
 	| "dev"
 	| "check"
+	| "submit-check"
+	| "bounty-check"
 	| "record"
 	| "test"
 	| "perf";
@@ -22,11 +24,9 @@ export const COMMAND_MANIFEST: Record<
 		name: "create",
 		summary:
 			"Scaffold a provider, install dependencies, run baseline validation, and print the next local-dev command.",
-		usage:
-			"apifuse create <provider-name> [--preset standalone|monorepo] [--json] [--dry-run]",
+		usage: "apifuse create <provider-name> [--json] [--dry-run]",
 		examples: [
 			"apifuse create weather-provider",
-			"apifuse create weather-provider --preset monorepo",
 			"apifuse create --config ./apifuse.create.json --json",
 		],
 		modulePath: "./apifuse-create",
@@ -36,24 +36,43 @@ export const COMMAND_MANIFEST: Record<
 		summary:
 			"Start the local provider dev server with the standard provider server contract.",
 		usage: "apifuse dev [path]",
-		examples: ["apifuse dev .", "apifuse dev providers/airkorea"],
+		examples: ["apifuse dev .", "apifuse dev providers/korea-air-quality"],
 		modulePath: "./apifuse-dev",
 	},
 	check: {
 		name: "check",
 		summary: "Validate provider structure, metadata, fixtures, and schemas.",
 		usage: "apifuse check [path]",
-		examples: ["apifuse check .", "apifuse check providers/airkorea"],
+		examples: ["apifuse check .", "apifuse check providers/korea-air-quality"],
 		modulePath: "./apifuse-check",
 	},
+	"submit-check": {
+		name: "submit-check",
+		summary:
+			"Score provider bounty submission readiness and emit checklist evidence.",
+		usage:
+			"apifuse submit-check [path] [--tier bronze|silver|gold|diamond] [--json] [--markdown <path>] [--smoke-note <text>]",
+		examples: [
+			"apifuse submit-check .",
+			"apifuse submit-check . --tier silver --markdown submission-report.md",
+		],
+		modulePath: "./apifuse-submit-check",
+	},
+	"bounty-check": {
+		name: "bounty-check",
+		summary: "Alias for submit-check.",
+		usage:
+			"apifuse bounty-check [path] [--tier bronze|silver|gold|diamond] [--json] [--markdown <path>] [--smoke-note <text>]",
+		examples: ["apifuse bounty-check . --markdown submission-report.md"],
+		modulePath: "./apifuse-submit-check",
+	},
 	record: {
 		name: "record",
 		summary: "Call a provider operation and capture upstream raw fixture data.",
 		usage:
 			'apifuse record [path] --operation <operation> --params \'{"value":"hello"}\'',
 		examples: [
-			'apifuse record . --operation ping --params \'{"value":"hello"}\'',
-			'apifuse record providers/airkorea --operation realtime --params \'{"stationName":"종로구"}\'',
+			'apifuse record providers/korea-air-quality --operation realtime --params \'{"stationName":"종로구"}\'',
 		],
 		modulePath: "./apifuse-record",
 	},
@@ -61,17 +80,20 @@ export const COMMAND_MANIFEST: Record<
 		name: "test",
 		summary: "Run provider-focused tests and surface actionable failures.",
 		usage: "apifuse test [path] [--json] [--verbose]",
-		examples: ["apifuse test .", "apifuse test providers/airkorea --json"],
+		examples: [
+			"apifuse test .",
+			"apifuse test providers/korea-air-quality --json",
+		],
 		modulePath: "./apifuse-test",
 	},
 	perf: {
 		name: "perf",
 		summary:
 			"Profile a provider operation and export latency/trace diagnostics.",
-		usage: "apifuse perf <path> --operation <operation> [options]",
+		usage:
+			"apifuse perf <path> --operation <operation> [--params '<json>'] [options]",
 		examples: [
-			"apifuse perf . --operation ping",
-			"apifuse perf providers/airkorea --operation realtime --runs 5",
+			'apifuse perf providers/korea-air-quality --operation realtime --params \'{"stationName":"종로구"}\' --runs 5',
 		],
 		modulePath: "./apifuse-perf",
 	},
@@ -81,6 +103,7 @@ export const COMMAND_ORDER: ApifuseCommandName[] = [
 	"create",
 	"dev",
 	"check",
+	"submit-check",
 	"record",
 	"test",
 	"perf",