feat(secop): Tier 1 — SECOP-aligned verifier, schemas, and crypto (#51)

* feat(secop): Tier 1 — SECOP-aligned verifier, schemas, and crypto

Schemas / types:
- PolicyGrantLike + verification schema: add velocityLimit, maxSpend,
  offlineMaxCumulativePayment, destinationAllowlist, merchantCredentialIssuer,
  activeGrantCredentialIssuer, gatewayCredentialIssuer, subjectCredentialIssuer,
  operatorId
- CreatePolicyGrantInput: all new fields wired through
- PaymentPolicyDecision: add purpose field (SECOP 1a)
- FPA schema: allowedAssets accepts structured Asset objects
- SettlementVerificationContext: gatewayAddress, purpose, expectedActorId,
  budgetIdStore, clockDriftToleranceMs, grantCumulativeSpentMinor,
  fleetPolicyAuthorization

Verifier pipeline (SECOP checks):
- Step 0a: optional FleetPolicyAuthorization verification (10c)
- authorizedGateway check (6b)
- allowedPurposes enforcement (1a)
- budgetId replay prevention via BudgetIdStore interface (4a / 3b)
- actorId binding validation (5a-c)
- grant-level budgetMinor ceiling check (10a)
- grant-level destinationAllowlist check (1b)
- Clock drift tolerance (default 5 min) on all expiry checks (3d)

New modules:
- src/verifier/budgetIdStore.ts — BudgetIdStore + InMemoryBudgetIdStore
- src/verifier/verifyFpa.ts — FPA signature, expiry, intersection
- src/hash/lowS.ts — secp256k1 low-S normalization (8b)
- src/hash/policyHash.ts — domain-separated policy document hash (10a)
- src/protocol/jwksResolver.ts — HTTPS JWKS fetch with active/alg (2a, 8a)

Tests updated for clock drift tolerance (clockDriftToleranceMs: 0 for
strict expiry tests). All 191 tests pass.

Made-with: Cursor

* fix: review findings — forward clockDriftToleranceMs to SBA, sync-only BudgetIdStore, cleanup cast

Bug 1: clockDriftToleranceMs was not forwarded from verifyBudgetAuthorization
to verifySignedSessionBudgetAuthorizationForDecision, causing the SBA expiry
check to silently use the 5-minute default regardless of pipeline config.

Bug 2: BudgetIdStore.markSeen returned boolean | Promise<boolean> but the
pipeline never awaited, so async stores always failed as replays. The interface
is now sync-only with guidance for async backing stores.

Cleanup: removed unnecessary type assertion in verifyFpa.ts — Zod already
provides the correct type after safeParse.

Adds 62 tests covering all new SECOP checks: authorizedGateway, allowedPurposes,
budgetId replay, actorId binding, budgetMinor ceiling, destinationAllowlist,
FPA verification, clock drift propagation, lowS normalization, and policyHash.

Made-with: Cursor

---------

Co-authored-by: NAOR YUVAL <naoryuval@NAORs-MacBook-Air.local>

Author: naory

src/hash/index.ts

@@ -1,2 +1,4 @@
 export { canonicalJson } from "./canonicalJson.js";
 export { sha256Hex } from "./sha256.js";
+export { hashPolicyDocument } from "./policyHash.js";
+export { isLowS, ensureLowS } from "./lowS.js";

src/hash/lowS.ts

@@ -0,0 +1,90 @@
+/**
+ * secp256k1 low-S normalization (SECOP 8b).
+ *
+ * ECDSA signatures over secp256k1 are malleable: given (r, s) a valid signature,
+ * (r, n − s) is also valid. MPCP requires the canonical "low-S" form where
+ * s ≤ n/2. This matches Bitcoin's standardness rule (BIP 62) and prevents
+ * third-party malleability.
+ */
+
+const SECP256K1_ORDER = BigInt(
+  "0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141",
+);
+const SECP256K1_HALF_ORDER = SECP256K1_ORDER >> 1n;
+
+/**
+ * Return true if the S value in a DER-encoded secp256k1 ECDSA signature
+ * is in the low half (s <= n/2).
+ */
+export function isLowS(derSignature: Buffer): boolean {
+  const s = extractSFromDer(derSignature);
+  if (s === null) return false;
+  return s <= SECP256K1_HALF_ORDER;
+}
+
+/**
+ * If S > n/2, replace it with n − S (canonical low-S form).
+ * Returns a new DER buffer or the original if already canonical.
+ */
+export function ensureLowS(derSignature: Buffer): Buffer {
+  const s = extractSFromDer(derSignature);
+  if (s === null) return derSignature;
+  if (s <= SECP256K1_HALF_ORDER) return derSignature;
+
+  const newS = SECP256K1_ORDER - s;
+  return replaceSInDer(derSignature, newS);
+}
+
+function extractSFromDer(der: Buffer): bigint | null {
+  if (der.length < 8 || der[0] !== 0x30) return null;
+  let offset = 2;
+  if (der[1] & 0x80) offset += (der[1] & 0x7f);
+
+  // R
+  if (der[offset] !== 0x02) return null;
+  const rLen = der[offset + 1]!;
+  offset += 2 + rLen;
+
+  // S
+  if (offset >= der.length || der[offset] !== 0x02) return null;
+  const sLen = der[offset + 1]!;
+  const sBytes = der.subarray(offset + 2, offset + 2 + sLen);
+  return bufToBigInt(sBytes);
+}
+
+function bufToBigInt(buf: Uint8Array): bigint {
+  let result = 0n;
+  for (const byte of buf) result = (result << 8n) | BigInt(byte);
+  return result;
+}
+
+function bigIntToBuf(n: bigint): Buffer {
+  let hex = n.toString(16);
+  if (hex.length % 2) hex = "0" + hex;
+  const buf = Buffer.from(hex, "hex");
+  if (buf[0]! >= 0x80) return Buffer.concat([Buffer.from([0x00]), buf]);
+  return buf;
+}
+
+function replaceSInDer(der: Buffer, newS: bigint): Buffer {
+  let offset = 2;
+  if (der[1]! & 0x80) offset += (der[1]! & 0x7f);
+
+  // R header + body
+  const rLen = der[offset + 1]!;
+  const rPart = der.subarray(offset, offset + 2 + rLen);
+
+  // Build new S TLV
+  const sBuf = bigIntToBuf(newS);
+  const sTlv = Buffer.concat([Buffer.from([0x02, sBuf.length]), sBuf]);
+
+  // Reassemble
+  const inner = Buffer.concat([rPart, sTlv]);
+  const outerLen = inner.length;
+  if (outerLen <= 127) {
+    return Buffer.concat([Buffer.from([0x30, outerLen]), inner]);
+  }
+  const lenBytes = outerLen <= 0xff ? Buffer.from([0x81, outerLen])
+    : Buffer.from([0x82, (outerLen >> 8) & 0xff, outerLen & 0xff]);
+  return Buffer.concat([Buffer.from([0x30]), lenBytes, inner]);
+}

src/hash/policyHash.ts

@@ -0,0 +1,23 @@
+/**
+ * Domain-separated policy document hashing (SECOP 10a / spec alignment).
+ *
+ * Per PolicyGrant.md § Policy Hashing:
+ *   policyHash = SHA256("MPCP:Policy:<version>:" || canonicalJson(policyDocument))
+ */
+
+import { createHash } from "node:crypto";
+import { canonicalJson } from "./canonicalJson.js";
+
+/**
+ * Compute the spec-compliant policy hash for a policy document.
+ *
+ * @param policyDocument - The structured policy document object
+ * @param version - Protocol version (default "1.0")
+ * @returns Lowercase hex SHA-256 digest
+ */
+export function hashPolicyDocument(policyDocument: unknown, version = "1.0"): string {
+  const prefix = `MPCP:Policy:${version}:`;
+  return createHash("sha256")
+    .update(prefix + canonicalJson(policyDocument))
+    .digest("hex");
+}

src/policy-core/types.ts

@@ -177,6 +177,8 @@ export interface PaymentPolicyDecision {
   chosen?: { rail: Rail; quoteId: string };
   createdAt?: string;
   maxSpend?: { perTxMinor?: string; perSessionMinor?: string; perDayMinor?: string };
+  /** Payment purpose / merchant category for allowedPurposes enforcement. */
+  purpose?: string;
 }
 
 export interface SettlementResult {

src/protocol/jwksResolver.ts

@@ -0,0 +1,94 @@
+/**
+ * HTTPS JWKS key resolution (SECOP 2a / 8a).
+ *
+ * Step 3 of the MPCP 3-step key resolution algorithm:
+ *   1. Trust Bundle (offline)
+ *   2. Pre-configured key (env var)
+ *   3. HTTPS well-known endpoint  ← this module
+ *
+ * Fetches /.well-known/mpcp-keys.json from the issuer's domain, filters by
+ * `active` field (SECOP 2a), and optionally validates the `alg` field (SECOP 8a).
+ */
+
+import type { KeyWithKid } from "./trustBundle.js";
+
+export interface JwksResolverOptions {
+  /** Timeout in ms for the HTTPS fetch. Default 5000. */
+  timeoutMs?: number;
+  /** Required algorithm — reject keys whose `alg` does not match. */
+  requiredAlg?: string;
+}
+
+export interface JwksDocument {
+  keys: (KeyWithKid & { active?: boolean; alg?: string })[];
+}
+
+/**
+ * Fetch the JWKS document from an issuer's well-known endpoint.
+ *
+ * @param issuer - Domain or did:web (only the domain part is used)
+ * @returns Parsed JWKS document, or null on failure
+ */
+export async function fetchJwks(
+  issuer: string,
+  options?: JwksResolverOptions,
+): Promise<JwksDocument | null> {
+  const domain = issuerToDomain(issuer);
+  if (!domain) return null;
+
+  const url = `https://${domain}/.well-known/mpcp-keys.json`;
+  const timeoutMs = options?.timeoutMs ?? 5000;
+
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const res = await fetch(url, { signal: controller.signal });
+    clearTimeout(timer);
+    if (!res.ok) return null;
+    return (await res.json()) as JwksDocument;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a specific key from a remote JWKS endpoint.
+ *
+ * Filters by:
+ *   - `kid` match
+ *   - `active !== false` (SECOP 2a: inactive keys are excluded)
+ *   - `alg` match when `options.requiredAlg` is set (SECOP 8a)
+ */
+export async function resolveFromJwks(
+  issuer: string,
+  issuerKeyId: string,
+  options?: JwksResolverOptions,
+): Promise<KeyWithKid | null> {
+  const doc = await fetchJwks(issuer, options);
+  if (!doc?.keys) return null;
+
+  for (const key of doc.keys) {
+    if (key.kid !== issuerKeyId) continue;
+    if (key.active === false) continue;
+    if (options?.requiredAlg && key.alg && key.alg !== options.requiredAlg) continue;
+    return key;
+  }
+  return null;
+}
+
+function issuerToDomain(issuer: string): string | null {
+  if (issuer.startsWith("did:web:")) {
+    return issuer.slice("did:web:".length).replace(/%3A/gi, ":");
+  }
+  if (issuer.startsWith("https://")) {
+    try {
+      return new URL(issuer).hostname;
+    } catch {
+      return null;
+    }
+  }
+  if (issuer.includes(".") && !issuer.includes(" ")) {
+    return issuer;
+  }
+  return null;
+}

src/protocol/sba.ts

@@ -112,7 +112,7 @@ export function createSignedSessionBudgetAuthorization(input: {
 
 export function verifySignedSessionBudgetAuthorizationForDecision(
   envelope: SignedSessionBudgetAuthorization,
-  input: { sessionId: string; decision: PaymentPolicyDecision; nowMs?: number; cumulativeSpentMinor?: string; trustBundles?: TrustBundle[] },
+  input: { sessionId: string; decision: PaymentPolicyDecision; nowMs?: number; cumulativeSpentMinor?: string; trustBundles?: TrustBundle[]; clockDriftToleranceMs?: number },
 ): { ok: true } | { ok: false; reason: "invalid_signature" | "expired" | "budget_exceeded" | "mismatch" } {
   // Key resolution per spec (3-step algorithm):
   //   1. Trust Bundle — offline JWK lookup by issuer + issuerKeyId
@@ -145,7 +145,8 @@ export function verifySignedSessionBudgetAuthorizationForDecision(
   if (!isValid) return { ok: false, reason: "invalid_signature" };
 
   const nowMs = typeof input.nowMs === "number" ? input.nowMs : Date.now();
-  if (Date.parse(envelope.authorization.expiresAt) <= nowMs) return { ok: false, reason: "expired" };
+  const driftMs = input.clockDriftToleranceMs ?? 300_000;
+  if (Date.parse(envelope.authorization.expiresAt) <= nowMs - driftMs) return { ok: false, reason: "expired" };
 
   const { authorization } = envelope;
   const { decision } = input;

src/protocol/schema/fleetPolicyAuthorization.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import {
   railSchema,
+  assetSchema,
   mpcpVersionSchema,
   currencySchema,
   minorUnitSchema,
@@ -19,7 +20,7 @@ export const fleetPolicyAuthorizationPayloadSchema = z.strictObject({
   minorUnit: minorUnitSchema,
   maxAmountMinor: z.string(),
   allowedRails: z.array(railSchema),
-  allowedAssets: z.array(z.string()),
+  allowedAssets: z.array(z.union([assetSchema, z.string()])),
   allowedOperators: z.array(z.string()),
   geoFence: z.array(z.string()).optional(),
   expiresAt: iso8601DatetimeSchema,

src/protocol/schema/verifySchemas.ts

@@ -6,8 +6,19 @@ import {
   iso8601DatetimeSchema,
 } from "./shared.js";
 
+const velocityLimitSchema = z.strictObject({
+  maxPayments: z.number().int().min(1),
+  windowSeconds: z.number().int().min(1),
+});
+
+const maxSpendSchema = z.object({
+  perTxMinor: z.string().optional(),
+  perSessionMinor: z.string().optional(),
+  perDayMinor: z.string().optional(),
+});
+
 /**
- * Minimal policy grant shape for verification.
+ * Policy grant shape for verification (SECOP-aligned).
  * Accepts expiresAt or expiresAtISO (at least one required).
  */
 export const policyGrantForVerificationSchema = z
@@ -30,6 +41,19 @@ export const policyGrantForVerificationSchema = z
     authorizedGateway: z.string().optional(),
     offlineMaxSinglePayment: z.string().regex(/^\d+$/).optional(),
     offlineMaxSinglePaymentCurrency: z.string().optional(),
+    offlineMaxCumulativePayment: z.string().regex(/^\d+$/).optional(),
+    offlineMaxCumulativePaymentCurrency: z.string().optional(),
+    velocityLimit: velocityLimitSchema.optional(),
+    maxSpend: maxSpendSchema.optional(),
+    destinationAllowlist: z.array(z.string()).optional(),
+    merchantCredentialIssuer: z.string().optional(),
+    merchantCredentialType: z.string().optional(),
+    activeGrantCredentialIssuer: z.string().optional(),
+    gatewayCredentialIssuer: z.string().optional(),
+    gatewayCredentialType: z.string().optional(),
+    subjectCredentialIssuer: z.string().optional(),
+    subjectCredentialType: z.string().optional(),
+    operatorId: z.string().optional(),
   })
   .refine((g) => g.expiresAt != null || g.expiresAtISO != null, {
     message: "policy_grant_missing_expiry",

src/sdk/createPolicyGrant.ts

@@ -12,18 +12,25 @@ export interface CreatePolicyGrantInput {
   revocationEndpoint?: string;
   allowedPurposes?: string[];
   anchorRef?: string;
-  /** Total authorized spend in minor units (e.g. drops for XRP). Signed by the PA. */
   budgetMinor?: string;
-  /** Currency code for budgetMinor (e.g. "XRP"). Required when budgetMinor is set. */
   budgetCurrency?: string;
-  /** On-chain escrow locking budgetMinor. Format: "xrpl:escrow:{account}:{sequence}". Signed by the PA. */
   budgetEscrowRef?: string;
-  /** Address of the only gateway authorized to spend against this grant's escrow. Rail-specific format. PA-signed. */
   authorizedGateway?: string;
-  /** PA-signed per-transaction cap for offline merchant acceptance, in minor units (see offlineMaxSinglePaymentCurrency). */
   offlineMaxSinglePayment?: string;
-  /** Currency code for offlineMaxSinglePayment (e.g. "XRP"). */
   offlineMaxSinglePaymentCurrency?: string;
+  offlineMaxCumulativePayment?: string;
+  offlineMaxCumulativePaymentCurrency?: string;
+  velocityLimit?: { maxPayments: number; windowSeconds: number };
+  maxSpend?: { perTxMinor?: string; perSessionMinor?: string; perDayMinor?: string };
+  destinationAllowlist?: string[];
+  merchantCredentialIssuer?: string;
+  merchantCredentialType?: string;
+  activeGrantCredentialIssuer?: string;
+  gatewayCredentialIssuer?: string;
+  gatewayCredentialType?: string;
+  subjectCredentialIssuer?: string;
+  subjectCredentialType?: string;
+  operatorId?: string;
 }
 
 /**
@@ -33,20 +40,30 @@ export interface CreatePolicyGrantInput {
  * @returns Policy grant compatible with verifyPolicyGrant / verifySettlement
  */
 export function createPolicyGrant(input: CreatePolicyGrantInput): PolicyGrantLike {
-  return {
+  const grant: PolicyGrantLike = {
     grantId: input.grantId ?? randomUUID(),
     policyHash: input.policyHash,
     expiresAt: input.expiresAt,
     allowedRails: input.allowedRails,
     allowedAssets: input.allowedAssets ?? [],
-    ...(input.revocationEndpoint ? { revocationEndpoint: input.revocationEndpoint } : {}),
-    ...(input.allowedPurposes ? { allowedPurposes: input.allowedPurposes } : {}),
-    ...(input.anchorRef ? { anchorRef: input.anchorRef } : {}),
-    ...(input.budgetMinor ? { budgetMinor: input.budgetMinor } : {}),
-    ...(input.budgetCurrency ? { budgetCurrency: input.budgetCurrency } : {}),
-    ...(input.budgetEscrowRef ? { budgetEscrowRef: input.budgetEscrowRef } : {}),
-    ...(input.authorizedGateway ? { authorizedGateway: input.authorizedGateway } : {}),
-    ...(input.offlineMaxSinglePayment ? { offlineMaxSinglePayment: input.offlineMaxSinglePayment } : {}),
-    ...(input.offlineMaxSinglePaymentCurrency ? { offlineMaxSinglePaymentCurrency: input.offlineMaxSinglePaymentCurrency } : {}),
   };
+  const optionalFields: Array<keyof CreatePolicyGrantInput> = [
+    "revocationEndpoint", "allowedPurposes", "anchorRef",
+    "budgetMinor", "budgetCurrency", "budgetEscrowRef", "authorizedGateway",
+    "offlineMaxSinglePayment", "offlineMaxSinglePaymentCurrency",
+    "offlineMaxCumulativePayment", "offlineMaxCumulativePaymentCurrency",
+    "velocityLimit", "maxSpend", "destinationAllowlist",
+    "merchantCredentialIssuer", "merchantCredentialType",
+    "activeGrantCredentialIssuer",
+    "gatewayCredentialIssuer", "gatewayCredentialType",
+    "subjectCredentialIssuer", "subjectCredentialType",
+    "operatorId",
+  ];
+  for (const key of optionalFields) {
+    const val = input[key];
+    if (val !== undefined && val !== null) {
+      (grant as Record<string, unknown>)[key] = val;
+    }
+  }
+  return grant;
 }

src/sdk/index.ts

@@ -40,7 +40,7 @@ export type {
   PolicyDocumentCustody,
   XrplPolicyAnchorPreparation,
 } from "../anchor/index.js";
-export { canonicalJson } from "../hash/index.js";
+export { canonicalJson, hashPolicyDocument, isLowS, ensureLowS } from "../hash/index.js";
 
 export { signTrustBundle, verifyTrustBundle, resolveFromTrustBundle } from "../protocol/trustBundle.js";
 export type { TrustBundle, TrustBundleIssuerEntry, UnsignedTrustBundle, KeyWithKid } from "../protocol/trustBundle.js";
@@ -54,3 +54,7 @@ export {
   verifySettlementWithReportSafe,
   verifySettlementDetailedSafe,
 } from "../verifier/verifySettlement.js";
+export { verifyFleetPolicyAuthorization } from "../verifier/verifyFpa.js";
+export { InMemoryBudgetIdStore } from "../verifier/budgetIdStore.js";
+export type { BudgetIdStore } from "../verifier/budgetIdStore.js";
+export { fetchJwks, resolveFromJwks } from "../protocol/jwksResolver.js";