@nokinc-flur/sdk 2.0.0 → 2.2.0

package/dist/index.js

@@ -2958,6 +2958,9 @@ function createAccountsClient(opts) {
 import { z as z13 } from "zod";
 var Sha256Hex = z13.string().regex(/^[0-9a-f]{64}$/);
 var Base64Std3 = z13.string().regex(/^[A-Za-z0-9+/]+={0,2}$/);
+var ClaimNonce = z13.string().min(8).max(128).refine((value) => !value.includes("|"), {
+  message: "nonce must not contain |"
+});
 var ACCOUNT_FUNDED_OAC_MAX_TTL_MS = 1e3 * 60 * 60 * 24 * 7;
 var CONSUMER_OFFLINE_CLAIM_SUBMIT_GRACE_MS = 1e3 * 60 * 60 * 24;
 var AttestationSecurityLevelSchema = z13.enum([
@@ -3050,13 +3053,25 @@ var ConsumerPaymentClaimSchema = z13.object({
   payerUserId: z13.string().uuid(),
   payeeUserId: z13.string().uuid(),
   payerDeviceId: z13.string().min(1).max(128),
-  payerNonce: z13.string().min(8).max(128),
-  payeeNonce: z13.string().min(8).max(128),
+  payerNonce: ClaimNonce,
+  payeeNonce: ClaimNonce,
   amountKobo: z13.number().int().positive(),
   currency: z13.string().length(3).default("NGN"),
   occurredAtMs: z13.number().int().nonnegative(),
   completedAtMs: z13.number().int().nonnegative().optional(),
   contextId: z13.string().max(128).optional(),
+  requestId: z13.string().uuid().optional(),
+  requestMode: z13.enum(["fixed", "editable"]).optional(),
+  requestTakerUserId: z13.string().uuid().optional(),
+  requestAmountKobo: z13.number().int().positive().optional(),
+  requestCurrency: z13.string().length(3).optional(),
+  requestReference: z13.string().max(128).nullable().optional(),
+  requestCreatedAtMs: z13.number().int().nonnegative().optional(),
+  requestExpiresAtMs: z13.number().int().positive().optional(),
+  requestNonce: z13.string().min(8).max(128).optional(),
+  requestTakerDeviceId: z13.string().min(1).max(128).nullable().optional(),
+  requestTakerPubkeySpkiB64: Base64Std3.min(64).max(4096).optional(),
+  requestTakerSignatureDerB64: Base64Std3.min(16).max(2048).optional(),
   payerPubkeySpkiB64: Base64Std3.min(64).max(4096),
   payerSignatureDerB64: Base64Std3.min(16).max(2048),
   payeePubkeySpkiB64: Base64Std3.min(64).max(4096).optional(),
@@ -3076,7 +3091,10 @@ var ConsumerSettlementSchema = z13.object({
   ledgerRef: z13.string().nullable(),
   /** ASN.1 DER ECDSA P-256 issuer signature, base64. */
   issuerSig: Base64Std3.min(16).max(2048),
-  createdAtMs: z13.number().int().nonnegative()
+  /** Canonical millisecond timestamp signed into the settlement receipt. */
+  issuedAtMs: z13.number().int().nonnegative(),
+  /** Compatibility alias for API consumers that predate issuedAtMs. */
+  createdAtMs: z13.number().int().nonnegative().optional()
 });
 var ConsumerSettleResultSchema = z13.object({
   settlement: ConsumerSettlementSchema,
@@ -3165,13 +3183,21 @@ function createMeOfflineClient(opts) {
       "/v1/me/offline/claims",
       ConsumerPaymentClaimSchema.parse(claim),
       (raw) => ConsumerSettleResultSchema.parse(raw)
+    ),
+    getSettlement: (idOrKey) => call(
+      "GET",
+      `/v1/me/offline/settlements/${encodeURIComponent(idOrKey)}`,
+      void 0,
+      (raw) => ConsumerSettlementSchema.parse(raw)
     )
   };
 }
 
 // src/me-offline/signer.ts
 import { p256 as p2562 } from "@noble/curves/nist";
+import { sha256 as sha2564 } from "@noble/hashes/sha2";
 var CLAIM_DOMAIN_V2 = "flur:consumer-offline:v2:claim";
+var ENCOUNTER_DOMAIN2 = "flur:consumer-offline:v1:encounter";
 function canonicalClaimSigningPayload(claim) {
   return {
     domain: CLAIM_DOMAIN_V2,
@@ -3192,6 +3218,27 @@ function canonicalClaimSigningPayload(claim) {
 function canonicalClaimSigningBytes(claim) {
   return canonicalJSONBytes(canonicalClaimSigningPayload(claim));
 }
+function computeConsumerClaimEncounterId(input) {
+  const material = `${ENCOUNTER_DOMAIN2}|${[
+    assertEncounterPart("oacId", input.oacId),
+    assertEncounterPart("payerUserId", input.payerUserId),
+    assertEncounterPart("payeeUserId", input.payeeUserId),
+    assertEncounterPart("payerNonce", input.payerNonce),
+    assertEncounterPart("payeeNonce", input.payeeNonce)
+  ].join("|")}`;
+  return bytesToHex5(sha2564(new TextEncoder().encode(material)));
+}
+function assertEncounterPart(field, value) {
+  if (value.includes("|")) {
+    throw new Error(`consumer encounter id ${field} must not contain |`);
+  }
+  return value;
+}
+function bytesToHex5(bytes) {
+  let out = "";
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
+  return out;
+}
 function bytesToBase642(bytes) {
   if (typeof Buffer !== "undefined") {
     return Buffer.from(bytes).toString("base64");
@@ -3287,38 +3334,192 @@ function verifyClaimSignature(input) {
   }
 }
 
-// src/me-offline/sms.ts
-var OFFLINE_CLAIM_SMS_PREFIX = "FLURC1.";
-var TOKEN_RE = /(?:^|\s)(FLURC1\.[A-Za-z0-9_-]+={0,2})(?:\s|$)/;
-function encodeOfflineClaimSmsMessage(claim) {
-  const parsed = ConsumerPaymentClaimSchema.parse(claim);
-  const json = JSON.stringify(parsed);
-  return `${OFFLINE_CLAIM_SMS_PREFIX}${base64UrlEncodeUtf8(json)}`;
+// src/me-offline/request.ts
+import { z as z14 } from "zod";
+var Base64Std4 = z14.string().regex(/^[A-Za-z0-9+/]+={0,2}$/);
+var CONSUMER_PAYMENT_REQUEST_DOMAIN = "flur:consumer-offline:v1:request";
+var ConsumerPaymentRequestEnvelopeSchema = z14.object({
+  requestId: z14.string().uuid(),
+  mode: z14.enum(["fixed", "editable"]),
+  takerUserId: z14.string().uuid(),
+  amountKobo: z14.number().int().positive(),
+  currency: z14.string().length(3).default("NGN"),
+  reference: z14.string().max(128).nullable().default(null),
+  createdAtMs: z14.number().int().nonnegative(),
+  expiresAtMs: z14.number().int().positive(),
+  nonce: z14.string().min(8).max(128),
+  takerDeviceId: z14.string().min(1).max(128).nullable().default(null),
+  takerPubkeySpkiB64: Base64Std4.min(64).max(4096).optional(),
+  takerSignatureDerB64: Base64Std4.min(16).max(2048).optional()
+}).superRefine((value, ctx) => {
+  if (value.expiresAtMs <= value.createdAtMs) {
+    ctx.addIssue({
+      code: z14.ZodIssueCode.custom,
+      path: ["expiresAtMs"],
+      message: "expiresAtMs must be greater than createdAtMs"
+    });
+  }
+  const hasSignature = Boolean(
+    value.takerPubkeySpkiB64 || value.takerSignatureDerB64
+  );
+  if (value.mode === "fixed" || hasSignature) {
+    if (!value.takerDeviceId) {
+      ctx.addIssue({
+        code: z14.ZodIssueCode.custom,
+        path: ["takerDeviceId"],
+        message: "signed requests require takerDeviceId"
+      });
+    }
+    if (!value.takerPubkeySpkiB64) {
+      ctx.addIssue({
+        code: z14.ZodIssueCode.custom,
+        path: ["takerPubkeySpkiB64"],
+        message: "signed requests require takerPubkeySpkiB64"
+      });
+    }
+    if (!value.takerSignatureDerB64) {
+      ctx.addIssue({
+        code: z14.ZodIssueCode.custom,
+        path: ["takerSignatureDerB64"],
+        message: "signed requests require takerSignatureDerB64"
+      });
+    }
+  }
+});
+function buildConsumerPaymentRequest(input) {
+  const unsigned = {
+    requestId: input.requestId,
+    mode: input.mode,
+    takerUserId: input.takerUserId,
+    amountKobo: input.amountKobo,
+    currency: input.currency ?? "NGN",
+    reference: input.reference ?? null,
+    createdAtMs: input.createdAtMs,
+    expiresAtMs: input.expiresAtMs,
+    nonce: input.nonce,
+    takerDeviceId: input.takerDeviceId ?? null
+  };
+  if (unsigned.mode === "fixed" && !unsigned.takerDeviceId) {
+    throw new Error("fixed requests require takerDeviceId");
+  }
+  if (unsigned.expiresAtMs <= unsigned.createdAtMs) {
+    throw new Error("expiresAtMs must be greater than createdAtMs");
+  }
+  return unsigned;
 }
-function decodeOfflineClaimSmsMessage(message) {
-  const token = extractOfflineClaimSmsToken(message);
-  if (!token) {
-    throw new Error("offline claim SMS token not found");
+function consumerPaymentRequestSigningPayload(request) {
+  return {
+    domain: CONSUMER_PAYMENT_REQUEST_DOMAIN,
+    version: 1,
+    requestId: request.requestId,
+    mode: request.mode,
+    takerUserId: request.takerUserId,
+    amountKobo: request.amountKobo,
+    currency: request.currency,
+    reference: request.reference ?? null,
+    createdAtMs: request.createdAtMs,
+    expiresAtMs: request.expiresAtMs,
+    nonce: request.nonce,
+    takerDeviceId: request.takerDeviceId ?? null
+  };
+}
+function consumerPaymentRequestSigningBytes(request) {
+  return canonicalJSONBytes(consumerPaymentRequestSigningPayload(request));
+}
+async function signConsumerPaymentRequest(unsigned, signer) {
+  if (signer.alg !== "p256") {
+    throw new Error("consumer payment requests require p256 signer");
   }
-  const encoded = token.slice(OFFLINE_CLAIM_SMS_PREFIX.length);
+  const publicKey = await signer.getPublicKey();
+  if (publicKey.alg !== "p256") {
+    throw new Error("consumer payment requests require p256 public key");
+  }
+  const signature = await signer.sign(
+    consumerPaymentRequestSigningBytes(unsigned)
+  );
+  return ConsumerPaymentRequestEnvelopeSchema.parse({
+    ...unsigned,
+    takerPubkeySpkiB64: publicKey.publicKey,
+    takerSignatureDerB64: signature.signature
+  });
+}
+function verifyConsumerPaymentRequest(request) {
+  const parsed = ConsumerPaymentRequestEnvelopeSchema.safeParse(request);
+  if (!parsed.success) return false;
+  const value = parsed.data;
+  if (!value.takerPubkeySpkiB64 || !value.takerSignatureDerB64) return false;
+  return verifyClaimSignature({
+    alg: "p256",
+    bytes: consumerPaymentRequestSigningBytes(value),
+    signature: value.takerSignatureDerB64,
+    publicKey: value.takerPubkeySpkiB64
+  });
+}
+function isConsumerPaymentRequestExpired(request, nowMs = Date.now()) {
+  const parsed = ConsumerPaymentRequestEnvelopeSchema.parse(request);
+  return parsed.expiresAtMs <= nowMs;
+}
+
+// src/me-offline/settlement.ts
+var CONSUMER_SETTLEMENT_DOMAIN = "flur:consumer-offline:v1:settlement";
+var CONSUMER_SETTLEMENT_RECEIPT_QR_PREFIX = "FLURSR1.";
+function consumerSettlementSigningPayload(settlement) {
+  return {
+    domain: CONSUMER_SETTLEMENT_DOMAIN,
+    settlementId: settlement.settlementId,
+    settlementKey: settlement.settlementKey,
+    encounterId: settlement.encounterId,
+    oacId: settlement.oacId,
+    payerUserId: settlement.payerUserId,
+    payeeUserId: settlement.payeeUserId,
+    amountKobo: settlement.amountKobo,
+    currency: settlement.currency,
+    status: settlement.status,
+    reviewReason: settlement.reviewReason,
+    ledgerRef: settlement.ledgerRef,
+    issuedAtMs: settlement.issuedAtMs
+  };
+}
+function verifyConsumerSettlement(settlement, issuerPublicKeySpkiB64) {
+  const parsed = ConsumerSettlementSchema.safeParse(settlement);
+  if (!parsed.success) return false;
+  return verifyIssuerP256(
+    canonicalJSONBytes(consumerSettlementSigningPayload(parsed.data)),
+    parsed.data.issuerSig,
+    issuerPublicKeySpkiB64
+  );
+}
+function encodeConsumerSettlementReceiptQR(settlement) {
+  const parsed = ConsumerSettlementSchema.parse(settlement);
+  return `${CONSUMER_SETTLEMENT_RECEIPT_QR_PREFIX}${base64UrlEncodeUtf8(
+    JSON.stringify(parsed)
+  )}`;
+}
+function decodeUnverifiedConsumerSettlementReceiptQR(value) {
+  if (!value.startsWith(CONSUMER_SETTLEMENT_RECEIPT_QR_PREFIX)) {
+    throw new Error("not a Flur consumer settlement receipt QR");
+  }
+  const encoded = value.slice(CONSUMER_SETTLEMENT_RECEIPT_QR_PREFIX.length);
   let raw;
   try {
     raw = JSON.parse(base64UrlDecodeUtf8(encoded));
   } catch {
-    throw new Error("offline claim SMS token is malformed");
+    throw new Error("consumer settlement receipt QR is malformed");
   }
-  const parsed = ConsumerPaymentClaimSchema.safeParse(raw);
-  if (!parsed.success) {
-    throw new Error("offline claim SMS token is invalid");
+  return ConsumerSettlementSchema.parse(raw);
+}
+function verifyConsumerSettlementReceiptQR(value, issuerPublicKeySpkiB64) {
+  const settlement = decodeUnverifiedConsumerSettlementReceiptQR(value);
+  if (!verifyConsumerSettlement(settlement, issuerPublicKeySpkiB64)) {
+    throw new Error("consumer settlement receipt QR signature invalid");
   }
-  return parsed.data;
+  return settlement;
 }
-function extractOfflineClaimSmsToken(message) {
-  const trimmed = message.trim();
-  if (trimmed.startsWith(OFFLINE_CLAIM_SMS_PREFIX)) {
-    return trimmed.split(/\s+/, 1)[0] ?? null;
+function decodeConsumerSettlementReceiptQR(value, issuerPublicKeySpkiB64) {
+  if (!issuerPublicKeySpkiB64) {
+    return decodeUnverifiedConsumerSettlementReceiptQR(value);
   }
-  return TOKEN_RE.exec(message)?.[1] ?? null;
+  return verifyConsumerSettlementReceiptQR(value, issuerPublicKeySpkiB64);
 }
 function base64UrlEncodeUtf8(input) {
   const bytes = new TextEncoder().encode(input);
@@ -3348,15 +3549,281 @@ function base64UrlDecodeUtf8(input) {
   throw new Error("base64 decoder unavailable");
 }
 
+// src/me-offline/sms.ts
+import { p256 as p2563 } from "@noble/curves/nist";
+var OFFLINE_CLAIM_SMS_PREFIX = "FLURC1.";
+var CLAIM_TOKEN_RE = /(?:^|\s)(FLURC1\.[A-Za-z0-9_-]+={0,2})(?:\s|$)/;
+function encodeOfflineClaimSmsMessage(claim) {
+  const parsed = ConsumerPaymentClaimSchema.parse(claim);
+  return `${OFFLINE_CLAIM_SMS_PREFIX}${base64UrlEncodeUtf82(
+    JSON.stringify(parsed)
+  )}`;
+}
+function decodeOfflineClaimSmsMessage(message) {
+  const token = extractOfflineClaimSmsToken(message);
+  if (!token) throw new Error("offline claim QR token not found");
+  const encoded = token.slice(OFFLINE_CLAIM_SMS_PREFIX.length);
+  let raw;
+  try {
+    raw = JSON.parse(base64UrlDecodeUtf82(encoded));
+  } catch {
+    throw new Error("offline claim QR token is malformed");
+  }
+  const parsed = ConsumerPaymentClaimSchema.safeParse(raw);
+  if (!parsed.success) throw new Error("offline claim QR token is invalid");
+  return parsed.data;
+}
+function extractOfflineClaimSmsToken(message) {
+  const trimmed = message.trim();
+  if (trimmed.startsWith(OFFLINE_CLAIM_SMS_PREFIX)) {
+    return trimmed.split(/\s+/, 1)[0] ?? null;
+  }
+  return CLAIM_TOKEN_RE.exec(message)?.[1] ?? null;
+}
+var OFFLINE_SMS_SETTLE_PREFIX = "FLURA1.";
+var OFFLINE_SMS_SETTLE_DOMAIN = "flur:consumer-offline:v1:attest";
+var OFFLINE_SMS_SETTLE_TOKEN_BYTES = 112;
+var OFFLINE_SMS_SETTLE_HEADER_BYTES = 48;
+var OFFLINE_SMS_SETTLE_SIGNATURE_BYTES = 64;
+var OFFLINE_SMS_SETTLE_VERSION = 1;
+var TOKEN_RE = /(?:^|[\s,;:()<>"'])(FLURA1\.[A-Za-z0-9_-]{150})/;
+async function encodeOfflineSmsSettleToken(input, signer) {
+  const header = await buildSmsSettleHeader(input);
+  const sig = await signer.signRaw(domainTag(header));
+  if (sig.length !== OFFLINE_SMS_SETTLE_SIGNATURE_BYTES) {
+    throw new Error(
+      `FLURA1: signer returned ${sig.length}-byte sig; expected ${OFFLINE_SMS_SETTLE_SIGNATURE_BYTES}`
+    );
+  }
+  const out = new Uint8Array(OFFLINE_SMS_SETTLE_TOKEN_BYTES);
+  out.set(header, 0);
+  out.set(sig, OFFLINE_SMS_SETTLE_HEADER_BYTES);
+  return `${OFFLINE_SMS_SETTLE_PREFIX}${bytesToBase64Url(out)}`;
+}
+async function buildSmsSettleHeader(input) {
+  assertSafeUint64(input.amountKobo, "amountKobo");
+  if (input.amountKobo <= 0) {
+    throw new Error("FLURA1: amountKobo must be greater than zero");
+  }
+  assertSafeUint48(input.occurredAtMs, "occurredAtMs");
+  const encounterPrefix = (await sha2565(utf8(input.encounterId))).slice(0, 16);
+  const payerPrefix = uuidToBytes(input.payerUserId).slice(0, 8);
+  const payeePrefix = uuidToBytes(input.payeeUserId).slice(0, 8);
+  const header = new Uint8Array(OFFLINE_SMS_SETTLE_HEADER_BYTES);
+  const dv = new DataView(header.buffer);
+  header[0] = OFFLINE_SMS_SETTLE_VERSION;
+  header[1] = 0;
+  header.set(encounterPrefix, 2);
+  header.set(payerPrefix, 18);
+  header.set(payeePrefix, 26);
+  writeUint64BE(dv, 34, input.amountKobo);
+  writeUint48BE(dv, 42, input.occurredAtMs);
+  return header;
+}
+function domainTag(header) {
+  if (header.length !== OFFLINE_SMS_SETTLE_HEADER_BYTES) {
+    throw new Error(
+      `FLURA1: header must be ${OFFLINE_SMS_SETTLE_HEADER_BYTES} bytes`
+    );
+  }
+  const domain = utf8(OFFLINE_SMS_SETTLE_DOMAIN);
+  const out = new Uint8Array(domain.length + header.length);
+  out.set(domain, 0);
+  out.set(header, domain.length);
+  return out;
+}
+function decodeOfflineSmsSettleToken(message) {
+  const token = extractOfflineSmsSettleToken(message);
+  if (!token) throw new Error("FLURA1: token not found");
+  const encoded = token.slice(OFFLINE_SMS_SETTLE_PREFIX.length);
+  let bytes;
+  try {
+    bytes = base64UrlToBytes(encoded);
+  } catch {
+    throw new Error("FLURA1: token base64url is malformed");
+  }
+  if (bytesToBase64Url(bytes) !== encoded) {
+    throw new Error("FLURA1: token base64url is malformed");
+  }
+  if (bytes.length !== OFFLINE_SMS_SETTLE_TOKEN_BYTES) {
+    throw new Error(
+      `FLURA1: expected ${OFFLINE_SMS_SETTLE_TOKEN_BYTES} bytes, got ${bytes.length}`
+    );
+  }
+  const version = bytes[0];
+  const flags = bytes[1];
+  if (version !== OFFLINE_SMS_SETTLE_VERSION) {
+    throw new Error(`FLURA1: unsupported version ${version}`);
+  }
+  if (flags !== 0) {
+    throw new Error(`FLURA1: reserved flags must be 0, got ${flags}`);
+  }
+  const header = bytes.slice(0, OFFLINE_SMS_SETTLE_HEADER_BYTES);
+  const signature = bytes.slice(OFFLINE_SMS_SETTLE_HEADER_BYTES);
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const amountKobo = readUint64BE(dv, 34);
+  if (amountKobo <= 0) {
+    throw new Error("FLURA1: amountKobo must be greater than zero");
+  }
+  return {
+    version,
+    flags,
+    encounterIdPrefixHex: bytesToHex6(bytes.slice(2, 18)),
+    payerUserIdPrefixHex: bytesToHex6(bytes.slice(18, 26)),
+    payeeUserIdPrefixHex: bytesToHex6(bytes.slice(26, 34)),
+    amountKobo,
+    occurredAtMs: readUint48BE(dv, 42),
+    signature,
+    header,
+    signedBytes: domainTag(header)
+  };
+}
+function extractOfflineSmsSettleToken(message) {
+  const trimmed = message.trim();
+  if (trimmed.startsWith(OFFLINE_SMS_SETTLE_PREFIX)) {
+    return trimmed.split(/\s+/, 1)[0] ?? null;
+  }
+  return TOKEN_RE.exec(message)?.[1] ?? null;
+}
+function verifyOfflineSmsSettleToken(decoded, payerPubkeySpkiB64) {
+  try {
+    const pubRaw = p256SpkiB64ToRaw(payerPubkeySpkiB64);
+    return p2563.verify(decoded.signature, decoded.signedBytes, pubRaw, {
+      prehash: true,
+      format: "compact"
+    });
+  } catch {
+    return false;
+  }
+}
+function derToRawP256Signature(derBytes) {
+  const sig = p2563.Signature.fromBytes(derBytes, "der");
+  const raw = sig.toBytes("compact");
+  if (raw.length !== OFFLINE_SMS_SETTLE_SIGNATURE_BYTES) {
+    throw new Error(
+      `FLURA1: DER\u2192raw produced ${raw.length} bytes; expected ${OFFLINE_SMS_SETTLE_SIGNATURE_BYTES}`
+    );
+  }
+  return raw;
+}
+function utf8(s) {
+  return new TextEncoder().encode(s);
+}
+async function sha2565(bytes) {
+  const subtle = typeof globalThis !== "undefined" && globalThis.crypto?.subtle || void 0;
+  if (subtle) {
+    const digest = await subtle.digest("SHA-256", bytes);
+    return new Uint8Array(digest);
+  }
+  const { sha256: nobleSha256 } = await import("@noble/hashes/sha2");
+  return nobleSha256(bytes);
+}
+function uuidToBytes(uuid) {
+  const hex = uuid.replace(/-/g, "").toLowerCase();
+  if (hex.length !== 32 || !/^[0-9a-f]{32}$/.test(hex)) {
+    throw new Error(`FLURA1: invalid UUID: ${uuid}`);
+  }
+  const out = new Uint8Array(16);
+  for (let i = 0; i < 16; i++) {
+    out[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+function assertSafeUint64(value, field) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`FLURA1: ${field} must be a non-negative integer`);
+  }
+  if (value > Number.MAX_SAFE_INTEGER) {
+    throw new Error(`FLURA1: ${field} exceeds Number.MAX_SAFE_INTEGER`);
+  }
+}
+function assertSafeUint48(value, field) {
+  assertSafeUint64(value, field);
+  if (value > 281474976710655) {
+    throw new Error(`FLURA1: ${field} exceeds uint48 range`);
+  }
+}
+function writeUint64BE(dv, offset, value) {
+  const high = Math.floor(value / 4294967296);
+  const low = value >>> 0;
+  dv.setUint32(offset, high, false);
+  dv.setUint32(offset + 4, low, false);
+}
+function readUint64BE(dv, offset) {
+  const high = dv.getUint32(offset, false);
+  const low = dv.getUint32(offset + 4, false);
+  if (high > 2097151) {
+    throw new Error("FLURA1: amountKobo exceeds Number.MAX_SAFE_INTEGER");
+  }
+  return high * 4294967296 + low;
+}
+function writeUint48BE(dv, offset, value) {
+  const high = Math.floor(value / 65536);
+  const low = value & 65535;
+  dv.setUint32(offset, high, false);
+  dv.setUint16(offset + 4, low, false);
+}
+function readUint48BE(dv, offset) {
+  const high = dv.getUint32(offset, false);
+  const low = dv.getUint16(offset + 4, false);
+  return high * 65536 + low;
+}
+function bytesToHex6(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += bytes[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+function bytesToBase64Url(bytes) {
+  let base64;
+  if (typeof Buffer !== "undefined") {
+    base64 = Buffer.from(bytes).toString("base64");
+  } else {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    if (typeof btoa !== "function") {
+      throw new Error("FLURA1: base64 encoder unavailable");
+    }
+    base64 = btoa(binary);
+  }
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function base64UrlEncodeUtf82(input) {
+  return bytesToBase64Url(utf8(input));
+}
+function base64UrlDecodeUtf82(input) {
+  return new TextDecoder().decode(base64UrlToBytes(input));
+}
+function base64UrlToBytes(input) {
+  const base64 = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64.padEnd(
+    base64.length + (4 - base64.length % 4) % 4,
+    "="
+  );
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(padded, "base64"));
+  }
+  if (typeof atob !== "function") {
+    throw new Error("FLURA1: base64 decoder unavailable");
+  }
+  const binary = atob(padded);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
 // src/partner-funding/client.ts
-import { z as z14 } from "zod";
-var MinorString = z14.string().regex(/^-?\d+$/);
-var PositiveMinor = z14.union([
-  z14.number().int().positive(),
-  z14.string().regex(/^[1-9]\d{0,18}$/)
+import { z as z15 } from "zod";
+var MinorString = z15.string().regex(/^-?\d+$/);
+var PositiveMinor = z15.union([
+  z15.number().int().positive(),
+  z15.string().regex(/^[1-9]\d{0,18}$/)
 ]);
-var Currency = z14.string().trim().length(3).transform((v) => v.toUpperCase());
-var Metadata = z14.record(z14.unknown());
+var Currency = z15.string().trim().length(3).transform((v) => v.toUpperCase());
+var Metadata = z15.record(z15.unknown());
 var PARTNER_KINDS = ["bank", "merchant"];
 var CUSTODIAL_MODES = ["agent_of_bank", "flur_virtual_pool"];
 var PARTNER_PROFILE_STATUSES = [
@@ -3383,126 +3850,126 @@ var WITHDRAWAL_STATES = [
   "failed",
   "reversed"
 ];
-var PartnerProfileSchema = z14.object({
-  partnerAccountId: z14.string().uuid(),
-  kind: z14.enum(PARTNER_KINDS),
-  custodialMode: z14.enum(CUSTODIAL_MODES),
-  displayName: z14.string(),
-  bankCode: z14.string().nullable(),
-  poolAccountNumber: z14.string().nullable(),
-  status: z14.enum(PARTNER_PROFILE_STATUSES),
+var PartnerProfileSchema = z15.object({
+  partnerAccountId: z15.string().uuid(),
+  kind: z15.enum(PARTNER_KINDS),
+  custodialMode: z15.enum(CUSTODIAL_MODES),
+  displayName: z15.string(),
+  bankCode: z15.string().nullable(),
+  poolAccountNumber: z15.string().nullable(),
+  status: z15.enum(PARTNER_PROFILE_STATUSES),
   metadata: Metadata,
-  createdAtMs: z14.number().int().nonnegative(),
-  updatedAtMs: z14.number().int().nonnegative()
+  createdAtMs: z15.number().int().nonnegative(),
+  updatedAtMs: z15.number().int().nonnegative()
 });
-var UpsertPartnerProfileInputSchema = z14.object({
-  kind: z14.enum(PARTNER_KINDS),
-  custodialMode: z14.enum(CUSTODIAL_MODES),
-  displayName: z14.string().trim().min(1).max(200),
-  bankCode: z14.string().trim().min(1).max(64).optional(),
-  poolAccountNumber: z14.string().trim().min(1).max(64).optional(),
+var UpsertPartnerProfileInputSchema = z15.object({
+  kind: z15.enum(PARTNER_KINDS),
+  custodialMode: z15.enum(CUSTODIAL_MODES),
+  displayName: z15.string().trim().min(1).max(200),
+  bankCode: z15.string().trim().min(1).max(64).optional(),
+  poolAccountNumber: z15.string().trim().min(1).max(64).optional(),
   metadata: Metadata.optional()
 });
-var PartnerFundingEventInputSchema = z14.object({
-  externalRef: z14.string().trim().min(8).max(128),
-  direction: z14.enum(PARTNER_FUNDING_DIRECTIONS).optional(),
-  userId: z14.string().uuid().optional(),
-  accountId: z14.string().uuid().optional(),
+var PartnerFundingEventInputSchema = z15.object({
+  externalRef: z15.string().trim().min(8).max(128),
+  direction: z15.enum(PARTNER_FUNDING_DIRECTIONS).optional(),
+  userId: z15.string().uuid().optional(),
+  accountId: z15.string().uuid().optional(),
   amountMinor: PositiveMinor,
   currency: Currency,
-  fundingSource: z14.string().trim().min(1).max(64).optional(),
+  fundingSource: z15.string().trim().min(1).max(64).optional(),
   providerMetadata: Metadata.optional()
 });
-var PartnerFundingSchema = z14.object({
-  fundingId: z14.string().uuid(),
-  partnerId: z14.string().uuid(),
-  accountId: z14.string().uuid(),
-  userId: z14.string().uuid().nullable(),
-  direction: z14.enum(PARTNER_FUNDING_DIRECTIONS),
-  currency: z14.string(),
+var PartnerFundingSchema = z15.object({
+  fundingId: z15.string().uuid(),
+  partnerId: z15.string().uuid(),
+  accountId: z15.string().uuid(),
+  userId: z15.string().uuid().nullable(),
+  direction: z15.enum(PARTNER_FUNDING_DIRECTIONS),
+  currency: z15.string(),
   amountMinor: MinorString,
-  externalRef: z14.string(),
-  status: z14.enum(PARTNER_FUNDING_STATUSES),
-  fundingSource: z14.string(),
-  ledgerRef: z14.string(),
+  externalRef: z15.string(),
+  status: z15.enum(PARTNER_FUNDING_STATUSES),
+  fundingSource: z15.string(),
+  ledgerRef: z15.string(),
   providerMetadata: Metadata,
-  createdAtMs: z14.number().int().nonnegative(),
-  updatedAtMs: z14.number().int().nonnegative()
+  createdAtMs: z15.number().int().nonnegative(),
+  updatedAtMs: z15.number().int().nonnegative()
 });
-var IngestFundingResultSchema = z14.object({
+var IngestFundingResultSchema = z15.object({
   funding: PartnerFundingSchema,
-  replayed: z14.boolean()
+  replayed: z15.boolean()
 });
-var PayoutDestinationSchema = z14.object({
-  destinationId: z14.string().uuid(),
-  accountId: z14.string().uuid(),
-  partnerId: z14.string().uuid(),
-  bankCode: z14.string(),
-  accountNumber: z14.string(),
-  accountName: z14.string(),
-  status: z14.enum(PAYOUT_DESTINATION_STATUSES),
-  verifiedAtMs: z14.number().int().nonnegative().nullable(),
+var PayoutDestinationSchema = z15.object({
+  destinationId: z15.string().uuid(),
+  accountId: z15.string().uuid(),
+  partnerId: z15.string().uuid(),
+  bankCode: z15.string(),
+  accountNumber: z15.string(),
+  accountName: z15.string(),
+  status: z15.enum(PAYOUT_DESTINATION_STATUSES),
+  verifiedAtMs: z15.number().int().nonnegative().nullable(),
   metadata: Metadata,
-  createdAtMs: z14.number().int().nonnegative(),
-  updatedAtMs: z14.number().int().nonnegative()
+  createdAtMs: z15.number().int().nonnegative(),
+  updatedAtMs: z15.number().int().nonnegative()
 });
-var CreatePayoutDestinationInputSchema = z14.object({
-  partnerId: z14.string().uuid(),
-  bankCode: z14.string().trim().min(1).max(32),
-  accountNumber: z14.string().trim().min(4).max(64),
-  accountName: z14.string().trim().min(1).max(200),
+var CreatePayoutDestinationInputSchema = z15.object({
+  partnerId: z15.string().uuid(),
+  bankCode: z15.string().trim().min(1).max(32),
+  accountNumber: z15.string().trim().min(4).max(64),
+  accountName: z15.string().trim().min(1).max(200),
   metadata: Metadata.optional()
 });
-var ListPayoutDestinationsResultSchema = z14.object({
-  items: z14.array(PayoutDestinationSchema)
+var ListPayoutDestinationsResultSchema = z15.object({
+  items: z15.array(PayoutDestinationSchema)
 });
-var WithdrawalSchema = z14.object({
-  withdrawalId: z14.string().uuid(),
-  accountId: z14.string().uuid(),
-  userId: z14.string().uuid(),
-  partnerId: z14.string().uuid(),
-  destinationId: z14.string().uuid(),
-  currency: z14.string(),
+var WithdrawalSchema = z15.object({
+  withdrawalId: z15.string().uuid(),
+  accountId: z15.string().uuid(),
+  userId: z15.string().uuid(),
+  partnerId: z15.string().uuid(),
+  destinationId: z15.string().uuid(),
+  currency: z15.string(),
   amountMinor: MinorString,
-  state: z14.enum(WITHDRAWAL_STATES),
-  idempotencyKey: z14.string(),
-  providerRef: z14.string().nullable(),
-  lastError: z14.string().nullable(),
-  ledgerRef: z14.string(),
-  reverseLedgerRef: z14.string().nullable(),
+  state: z15.enum(WITHDRAWAL_STATES),
+  idempotencyKey: z15.string(),
+  providerRef: z15.string().nullable(),
+  lastError: z15.string().nullable(),
+  ledgerRef: z15.string(),
+  reverseLedgerRef: z15.string().nullable(),
   metadata: Metadata,
-  createdAtMs: z14.number().int().nonnegative(),
-  updatedAtMs: z14.number().int().nonnegative()
+  createdAtMs: z15.number().int().nonnegative(),
+  updatedAtMs: z15.number().int().nonnegative()
 });
-var CreateWithdrawalInputSchema = z14.object({
-  destinationId: z14.string().uuid(),
+var CreateWithdrawalInputSchema = z15.object({
+  destinationId: z15.string().uuid(),
   amountMinor: PositiveMinor,
   currency: Currency,
-  idempotencyKey: z14.string().trim().min(8).max(128),
+  idempotencyKey: z15.string().trim().min(8).max(128),
   metadata: Metadata.optional()
 });
-var CreateWithdrawalResultSchema = z14.object({
+var CreateWithdrawalResultSchema = z15.object({
   withdrawal: WithdrawalSchema,
-  replayed: z14.boolean()
+  replayed: z15.boolean()
 });
-var PayoutEventInputSchema = z14.object({
-  externalRef: z14.string().trim().min(8).max(128),
-  withdrawalId: z14.string().uuid().optional(),
-  state: z14.enum(["submitted", "processing", "paid", "failed"]),
-  providerRef: z14.string().trim().min(1).max(128).optional(),
-  failureCode: z14.string().trim().max(64).optional(),
-  failureMessage: z14.string().trim().max(512).optional(),
+var PayoutEventInputSchema = z15.object({
+  externalRef: z15.string().trim().min(8).max(128),
+  withdrawalId: z15.string().uuid().optional(),
+  state: z15.enum(["submitted", "processing", "paid", "failed"]),
+  providerRef: z15.string().trim().min(1).max(128).optional(),
+  failureCode: z15.string().trim().max(64).optional(),
+  failureMessage: z15.string().trim().max(512).optional(),
   providerMetadata: Metadata.optional()
 });
-var RecordPayoutEventResultSchema = z14.object({
+var RecordPayoutEventResultSchema = z15.object({
   withdrawal: WithdrawalSchema,
-  replayed: z14.boolean()
+  replayed: z15.boolean()
 });
-var ReconciliationReportSchema = z14.object({
-  partnerId: z14.string().uuid(),
-  currency: z14.string(),
-  fromMs: z14.number().int().nonnegative(),
-  toMs: z14.number().int().nonnegative(),
+var ReconciliationReportSchema = z15.object({
+  partnerId: z15.string().uuid(),
+  currency: z15.string(),
+  fromMs: z15.number().int().nonnegative(),
+  toMs: z15.number().int().nonnegative(),
   fundingsCreditMinor: MinorString,
   fundingsDebitMinor: MinorString,
   withdrawalsPaidMinor: MinorString,
@@ -3511,7 +3978,7 @@ var ReconciliationReportSchema = z14.object({
   expectedReserveBalanceMinor: MinorString,
   actualReserveBalanceMinor: MinorString,
   imbalanceMinor: MinorString,
-  generatedAtMs: z14.number().int().nonnegative()
+  generatedAtMs: z15.number().int().nonnegative()
 });
 function createPartnerFundingClient(partner) {
   return {
@@ -3663,19 +4130,19 @@ function createPartnerProfileAdminClient(opts) {
 }
 
 // src/artifacts/envelope.ts
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 var FLUR_ARTIFACT_URI_SCHEME = "flur";
 var FLUR_ARTIFACT_VERSION = 1;
 var FLUR_ARTIFACT_URI_PREFIX = `${FLUR_ARTIFACT_URI_SCHEME}://v${FLUR_ARTIFACT_VERSION}/`;
 var ArtifactTypeRe = /^[a-z][a-z0-9_]{1,63}$/;
-var ArtifactHeaderSchema = z15.object({
-  v: z15.literal(FLUR_ARTIFACT_VERSION),
-  t: z15.string().regex(ArtifactTypeRe, "invalid artifact type"),
-  iss: z15.string().min(1).max(128),
-  kid: z15.string().min(1).max(128),
-  iat: z15.number().int().nonnegative(),
-  exp: z15.number().int().positive().optional(),
-  nonce: z15.string().min(8).max(64).regex(/^[A-Za-z0-9_-]+$/, "nonce must be url-safe")
+var ArtifactHeaderSchema = z16.object({
+  v: z16.literal(FLUR_ARTIFACT_VERSION),
+  t: z16.string().regex(ArtifactTypeRe, "invalid artifact type"),
+  iss: z16.string().min(1).max(128),
+  kid: z16.string().min(1).max(128),
+  iat: z16.number().int().nonnegative(),
+  exp: z16.number().int().positive().optional(),
+  nonce: z16.string().min(8).max(64).regex(/^[A-Za-z0-9_-]+$/, "nonce must be url-safe")
 });
 var FlurArtifactError = class extends Error {
   constructor(message, code) {
@@ -3814,7 +4281,7 @@ function verifyArtifactSignature(decoded, publicKeySpkiB64, options = {}) {
 }
 
 // src/artifacts/types.ts
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 var ARTIFACT_TYPES = {
   OFFLINE_PAYMENT_AUTHORIZATION: "offline_payment_authorization",
   RECEIPT: "receipt",
@@ -3827,34 +4294,37 @@ var ARTIFACT_TYPES = {
   LEDGER_JOURNAL_ENTRY: "ledger_journal_entry",
   STATEMENT: "statement",
   PASS: "pass",
-  IDENTITY: "identity"
+  IDENTITY: "identity",
+  // Tier B: holder-signed identity attestation for offline trust. The
+  // envelope.iat / envelope.exp express the card's canonical lifetime.
+  PAY_CARD: "pay_card"
 };
-var HexString = (length) => z16.string().regex(
+var HexString = (length) => z17.string().regex(
   new RegExp(`^[0-9a-fA-F]{${length * 2}}$`),
   `expected ${length}-byte hex string`
 );
-var OfflinePaymentAuthorizationArtifactSchema = z16.object({
+var OfflinePaymentAuthorizationArtifactSchema = z17.object({
   authorization: OfflinePaymentAuthorizationSchema
 });
-var ReceiptArtifactSchema = z16.object({
-  receiptId: z16.string().min(1).max(64),
-  paymentReference: z16.string().min(1).max(64),
-  payerUserId: z16.string().min(1).max(64).optional(),
-  payeeUserId: z16.string().min(1).max(64),
-  amountKobo: z16.number().int().positive(),
-  currency: z16.literal("NGN"),
-  channel: z16.enum(["online", "offline_reconciled", "pay_link", "nqr"]),
-  settledAtMs: z16.number().int().positive(),
-  ledgerTxnId: z16.string().min(1).max(64).optional(),
-  memo: z16.string().max(140).optional(),
+var ReceiptArtifactSchema = z17.object({
+  receiptId: z17.string().min(1).max(64),
+  paymentReference: z17.string().min(1).max(64),
+  payerUserId: z17.string().min(1).max(64).optional(),
+  payeeUserId: z17.string().min(1).max(64),
+  amountKobo: z17.number().int().positive(),
+  currency: z17.literal("NGN"),
+  channel: z17.enum(["online", "offline_reconciled", "pay_link", "nqr"]),
+  settledAtMs: z17.number().int().positive(),
+  ledgerTxnId: z17.string().min(1).max(64).optional(),
+  memo: z17.string().max(140).optional(),
   hashChainPrev: HexString(32).optional()
 });
-var ShortId = z16.string().min(1).max(64);
-var PositiveInt = z16.number().int().positive();
-var NonNegativeInt = z16.number().int().nonnegative();
-var Currency2 = z16.literal("NGN");
-var Memo = z16.string().max(140);
-var NqrPaymentRequestArtifactSchema = z16.object({
+var ShortId = z17.string().min(1).max(64);
+var PositiveInt = z17.number().int().positive();
+var NonNegativeInt = z17.number().int().nonnegative();
+var Currency2 = z17.literal("NGN");
+var Memo = z17.string().max(140);
+var NqrPaymentRequestArtifactSchema = z17.object({
   requestId: ShortId,
   payeeUserId: ShortId,
   amountKobo: PositiveInt.optional(),
@@ -3862,7 +4332,7 @@ var NqrPaymentRequestArtifactSchema = z16.object({
   memo: Memo.optional(),
   expiresAtMs: PositiveInt.optional()
 });
-var PaymentIntentArtifactSchema = z16.object({
+var PaymentIntentArtifactSchema = z17.object({
   intentId: ShortId,
   payerUserId: ShortId,
   payeeUserId: ShortId,
@@ -3871,7 +4341,7 @@ var PaymentIntentArtifactSchema = z16.object({
   idempotencyKey: ShortId,
   createdAtMs: PositiveInt
 });
-var OfflineClaimArtifactSchema = z16.object({
+var OfflineClaimArtifactSchema = z17.object({
   claimId: ShortId,
   authorizationId: ShortId,
   payeeUserId: ShortId,
@@ -3880,10 +4350,10 @@ var OfflineClaimArtifactSchema = z16.object({
   claimedAtMs: PositiveInt,
   paymentReference: ShortId.optional()
 });
-var SettlementRecordArtifactSchema = z16.object({
+var SettlementRecordArtifactSchema = z17.object({
   settlementId: ShortId,
   ledgerTxnId: ShortId,
-  sourceRefType: z16.enum([
+  sourceRefType: z17.enum([
     "offline_authorization",
     "offline_claim",
     "transfer",
@@ -3894,12 +4364,12 @@ var SettlementRecordArtifactSchema = z16.object({
   currency: Currency2,
   settledAtMs: PositiveInt
 });
-var ReversalRecordArtifactSchema = z16.object({
+var ReversalRecordArtifactSchema = z17.object({
   reversalId: ShortId,
   originalTxnId: ShortId,
   amountKobo: PositiveInt,
   currency: Currency2,
-  reason: z16.enum([
+  reason: z17.enum([
     "user_dispute",
     "fraud",
     "duplicate",
@@ -3909,7 +4379,7 @@ var ReversalRecordArtifactSchema = z16.object({
   reversedAtMs: PositiveInt,
   memo: Memo.optional()
 });
-var LedgerJournalEntryArtifactSchema = z16.object({
+var LedgerJournalEntryArtifactSchema = z17.object({
   entryId: ShortId,
   journalId: ShortId,
   debitAccountId: ShortId,
@@ -3920,13 +4390,13 @@ var LedgerJournalEntryArtifactSchema = z16.object({
   refType: ShortId.optional(),
   refId: ShortId.optional()
 });
-var StatementArtifactSchema = z16.object({
+var StatementArtifactSchema = z17.object({
   statementId: ShortId,
   userId: ShortId,
   periodStartMs: PositiveInt,
   periodEndMs: PositiveInt,
-  openingBalanceKobo: z16.number().int(),
-  closingBalanceKobo: z16.number().int(),
+  openingBalanceKobo: z17.number().int(),
+  closingBalanceKobo: z17.number().int(),
   transactionCount: NonNegativeInt,
   currency: Currency2,
   hashChainPrev: HexString(32).optional()
@@ -3934,16 +4404,16 @@ var StatementArtifactSchema = z16.object({
   message: "periodEndMs must be greater than periodStartMs",
   path: ["periodEndMs"]
 });
-var PassArtifactSchema = z16.object({
+var PassArtifactSchema = z17.object({
   passId: ShortId,
   holderId: ShortId,
-  category: z16.enum(["membership", "ticket", "loyalty", "access", "voucher"]),
-  title: z16.string().min(1).max(120),
+  category: z17.enum(["membership", "ticket", "loyalty", "access", "voucher"]),
+  title: z17.string().min(1).max(120),
   validFromMs: PositiveInt,
   validUntilMs: PositiveInt.optional(),
-  metadata: z16.record(
-    z16.string().min(1).max(64),
-    z16.union([z16.string().max(280), z16.number(), z16.boolean()])
+  metadata: z17.record(
+    z17.string().min(1).max(64),
+    z17.union([z17.string().max(280), z17.number(), z17.boolean()])
   ).optional()
 }).refine(
   (v) => v.validUntilMs === void 0 || v.validUntilMs > v.validFromMs,
@@ -3952,10 +4422,10 @@ var PassArtifactSchema = z16.object({
     path: ["validUntilMs"]
   }
 );
-var IdentityArtifactSchema = z16.object({
+var IdentityArtifactSchema = z17.object({
   attestationId: ShortId,
   subjectId: ShortId,
-  claimType: z16.enum([
+  claimType: z17.enum([
     "phone_verified",
     "email_verified",
     "bvn_verified",
@@ -3965,6 +4435,12 @@ var IdentityArtifactSchema = z16.object({
   claimValueHash: HexString(32),
   attestedAtMs: PositiveInt
 });
+var PayCardArtifactSchema = z17.object({
+  userId: ShortId,
+  phoneE164: z17.string().regex(/^\+[1-9]\d{7,14}$/, "phoneE164 must be normalised E.164"),
+  displayName: z17.string().min(1).max(64),
+  devicePubKeySpkiB64: z17.string().min(64).max(256).regex(/^[A-Za-z0-9+/]+=*$/, "devicePubKeySpkiB64 must be standard base64")
+});
 var ARTIFACT_BODY_SCHEMAS = {
   [ARTIFACT_TYPES.OFFLINE_PAYMENT_AUTHORIZATION]: OfflinePaymentAuthorizationArtifactSchema,
   [ARTIFACT_TYPES.RECEIPT]: ReceiptArtifactSchema,
@@ -3976,7 +4452,8 @@ var ARTIFACT_BODY_SCHEMAS = {
   [ARTIFACT_TYPES.LEDGER_JOURNAL_ENTRY]: LedgerJournalEntryArtifactSchema,
   [ARTIFACT_TYPES.STATEMENT]: StatementArtifactSchema,
   [ARTIFACT_TYPES.PASS]: PassArtifactSchema,
-  [ARTIFACT_TYPES.IDENTITY]: IdentityArtifactSchema
+  [ARTIFACT_TYPES.IDENTITY]: IdentityArtifactSchema,
+  [ARTIFACT_TYPES.PAY_CARD]: PayCardArtifactSchema
 };
 var HARDENED_ARTIFACT_TYPES = /* @__PURE__ */ new Set([
   ARTIFACT_TYPES.OFFLINE_PAYMENT_AUTHORIZATION,
@@ -3989,7 +4466,8 @@ var HARDENED_ARTIFACT_TYPES = /* @__PURE__ */ new Set([
   ARTIFACT_TYPES.LEDGER_JOURNAL_ENTRY,
   ARTIFACT_TYPES.STATEMENT,
   ARTIFACT_TYPES.PASS,
-  ARTIFACT_TYPES.IDENTITY
+  ARTIFACT_TYPES.IDENTITY,
+  ARTIFACT_TYPES.PAY_CARD
 ]);
 function isKnownArtifactType(t) {
   return Object.values(ARTIFACT_TYPES).includes(t);
@@ -4074,6 +4552,130 @@ function createOfflinePaymentAuthorizationArtifactUri(input) {
     type: ARTIFACT_TYPES.OFFLINE_PAYMENT_AUTHORIZATION
   });
 }
+
+// src/artifacts/paycard.ts
+var PAY_CARD_DEFAULT_TTL_MS = 90 * 24 * 60 * 60 * 1e3;
+var PAY_CARD_REFRESH_THRESHOLD_MS = 30 * 24 * 60 * 60 * 1e3;
+var PAY_CARD_URI_PREFIX = `${FLUR_ARTIFACT_URI_PREFIX}${ARTIFACT_TYPES.PAY_CARD}/`;
+function createPayCardArtifactUri(input) {
+  if (input.data.userId !== input.issuer) {
+    throw new FlurArtifactError(
+      "pay_card.data.userId must equal envelope issuer",
+      "INVALID_BODY"
+    );
+  }
+  const iat = input.issuedAtSeconds ?? Math.floor(Date.now() / 1e3);
+  const exp = input.expiresAtSeconds ?? iat + Math.floor(PAY_CARD_DEFAULT_TTL_MS / 1e3);
+  return createArtifactUri({
+    type: ARTIFACT_TYPES.PAY_CARD,
+    issuer: input.issuer,
+    keyId: input.keyId,
+    privateKey: input.privateKey,
+    nonce: input.nonce,
+    issuedAtSeconds: iat,
+    expiresAtSeconds: exp,
+    data: input.data
+  });
+}
+function isPayCardArtifactUri(uri) {
+  return typeof uri === "string" && uri.startsWith(PAY_CARD_URI_PREFIX);
+}
+function decodePayCardArtifact(uri) {
+  if (!isPayCardArtifactUri(uri)) {
+    throw new FlurArtifactError(
+      `URI does not start with ${PAY_CARD_URI_PREFIX}`,
+      "INVALID_URI"
+    );
+  }
+  const decoded = decodeArtifactUri(uri);
+  if (decoded.type !== ARTIFACT_TYPES.PAY_CARD) {
+    throw new FlurArtifactError(
+      `Expected pay_card, got ${decoded.type}`,
+      "TYPE_MISMATCH"
+    );
+  }
+  const parsed = PayCardArtifactSchema.safeParse(decoded.body.data);
+  if (!parsed.success) {
+    throw new FlurArtifactError(
+      `pay_card body invalid: ${parsed.error.message}`,
+      "INVALID_BODY"
+    );
+  }
+  if (parsed.data.userId !== decoded.body.iss) {
+    throw new FlurArtifactError(
+      "pay_card.data.userId must equal envelope issuer",
+      "INVALID_BODY"
+    );
+  }
+  return {
+    body: {
+      ...decoded.body,
+      data: parsed.data
+    },
+    sig: decoded.sig,
+    decoded
+  };
+}
+function verifyPayCardArtifact(uri, publicKeySpkiB64, options = {}) {
+  if (!isPayCardArtifactUri(uri)) {
+    throw new FlurArtifactError(
+      `URI does not start with ${PAY_CARD_URI_PREFIX}`,
+      "INVALID_URI"
+    );
+  }
+  const verified = verifyArtifactUri(
+    uri,
+    publicKeySpkiB64,
+    options
+  );
+  if (verified.decoded.type !== ARTIFACT_TYPES.PAY_CARD) {
+    throw new FlurArtifactError(
+      `Expected pay_card, got ${verified.decoded.type}`,
+      "TYPE_MISMATCH"
+    );
+  }
+  if (verified.body.data.userId !== verified.body.iss) {
+    throw new FlurArtifactError(
+      "pay_card.data.userId must equal envelope issuer",
+      "INVALID_BODY"
+    );
+  }
+  return {
+    body: verified.body,
+    sig: verified.sig,
+    decoded: verified.decoded
+  };
+}
+function inspectPayCardFreshness(decoded, nowMs = Date.now()) {
+  const exp = decoded.body.exp;
+  if (exp === void 0) return "no_expiry";
+  const remainingMs = exp * 1e3 - nowMs;
+  if (remainingMs <= 0) return "expired";
+  if (remainingMs <= PAY_CARD_REFRESH_THRESHOLD_MS)
+    return "refresh_recommended";
+  return "fresh";
+}
+function buildPayCardSigningInput(input) {
+  if (input.data.userId !== input.issuer) {
+    throw new FlurArtifactError(
+      "pay_card.data.userId must equal envelope issuer",
+      "INVALID_BODY"
+    );
+  }
+  const parsedData = PayCardArtifactSchema.parse(input.data);
+  const iat = input.issuedAtSeconds ?? Math.floor(Date.now() / 1e3);
+  const exp = input.expiresAtSeconds ?? iat + Math.floor(PAY_CARD_DEFAULT_TTL_MS / 1e3);
+  const body = buildArtifactBody({
+    type: ARTIFACT_TYPES.PAY_CARD,
+    issuer: input.issuer,
+    keyId: input.keyId,
+    data: parsedData,
+    nonce: input.nonce,
+    issuedAtSeconds: iat,
+    expiresAtSeconds: exp
+  });
+  return { body, bodyBytes: canonicalJSONBytes(body) };
+}
 export {
   ACCOUNT_FUNDED_OAC_MAX_TTL_MS,
   ACCOUNT_STATUSES,
@@ -4090,6 +4692,9 @@ export {
   COLLECTION_INTENT_STATUSES,
   COLLECTION_PAYMENT_STATUSES,
   CONSUMER_OFFLINE_CLAIM_SUBMIT_GRACE_MS,
+  CONSUMER_PAYMENT_REQUEST_DOMAIN,
+  CONSUMER_SETTLEMENT_DOMAIN,
+  CONSUMER_SETTLEMENT_RECEIPT_QR_PREFIX,
   CUSTODIAL_MODES,
   CollectionIntentSchema,
   CollectionPaymentResultSchema,
@@ -4099,6 +4704,7 @@ export {
   OACRecordSchema as ConsumerOACRecordSchema,
   ConsumerOACSchema,
   ConsumerPaymentClaimSchema,
+  ConsumerPaymentRequestEnvelopeSchema,
   ConsumerSettleResultSchema,
   ConsumerSettlementSchema,
   CreateCollectionIntentInputSchema,
@@ -4140,6 +4746,12 @@ export {
   OAC_DEFAULT_PER_TX_KOBO,
   OAC_DEFAULT_VALIDITY_MS,
   OFFLINE_CLAIM_SMS_PREFIX,
+  OFFLINE_SMS_SETTLE_DOMAIN,
+  OFFLINE_SMS_SETTLE_HEADER_BYTES,
+  OFFLINE_SMS_SETTLE_PREFIX,
+  OFFLINE_SMS_SETTLE_SIGNATURE_BYTES,
+  OFFLINE_SMS_SETTLE_TOKEN_BYTES,
+  OFFLINE_SMS_SETTLE_VERSION,
   OfflineClaimArtifactSchema,
   OfflinePaymentAuthorizationArtifactSchema,
   OfflinePaymentAuthorizationSchema,
@@ -4157,6 +4769,9 @@ export {
   PASS_STATES,
   PAYLOAD_FORMAT_INDICATOR_VALUE,
   PAYOUT_DESTINATION_STATUSES,
+  PAY_CARD_DEFAULT_TTL_MS,
+  PAY_CARD_REFRESH_THRESHOLD_MS,
+  PAY_CARD_URI_PREFIX,
   POINT_OF_INITIATION,
   PartnerFundingEventInputSchema,
   PartnerFundingSchema,
@@ -4164,6 +4779,7 @@ export {
   PassArtifactSchema,
   PassMetadataSchema,
   PassSchema,
+  PayCardArtifactSchema,
   PayCollectionInputSchema,
   PaymentClaimSchema,
   PaymentIntentArtifactSchema,
@@ -4199,18 +4815,26 @@ export {
   bodySha256Hex,
   buildArtifactBody,
   buildAuthorization,
+  buildConsumerPaymentRequest,
   buildOAC,
   buildPass,
+  buildPayCardSigningInput,
   buildPaymentRequest,
   buildReceipt,
   buildRedemption,
+  buildSmsSettleHeader,
+  domainTag as buildSmsSettleSignedBytes,
   canonicalClaimSigningBytes,
   canonicalClaimSigningPayload,
   canonicalJSONBytes,
   canonicalJSONStringify,
   canonicalRequestString,
+  computeConsumerClaimEncounterId,
   computeEncounterId,
   constantTimeEqual,
+  consumerPaymentRequestSigningBytes,
+  consumerPaymentRequestSigningPayload,
+  consumerSettlementSigningPayload,
   crc16ccitt,
   crc16ccittHex,
   createAccountsClient,
@@ -4228,28 +4852,40 @@ export {
   createPartnerFundingClient,
   createPartnerProfileAdminClient,
   createPassesClient,
+  createPayCardArtifactUri,
   createReceiptArtifactUri,
   createReceiptsClient,
   createSoftwareP256Signer,
   decodeArtifactUri,
   decodeAuthorizationQR,
   decodeBase45,
+  decodeConsumerSettlementReceiptQR,
   decodeOfflineClaimSmsMessage,
+  decodeOfflineSmsSettleToken,
+  decodePayCardArtifact,
   decodePaymentRequestQR,
+  decodeUnverifiedConsumerSettlementReceiptQR,
+  derToRawP256Signature,
   encodeArtifactUri,
   encodeAuthorizationQR,
   encodeBase45,
+  encodeConsumerSettlementReceiptQR,
   encodeNQR,
   encodeOfflineClaimSmsMessage,
+  encodeOfflineSmsSettleToken,
   encodePaymentRequestQR,
   extractOfflineClaimSmsToken,
+  extractOfflineSmsSettleToken,
   formatAmount,
   generateDynamicQR,
   generateStaticQR,
   init,
+  inspectPayCardFreshness,
+  isConsumerPaymentRequestExpired,
   isHardenedArtifactType,
   isKnownArtifactType,
   isPassWithinValidity,
+  isPayCardArtifactUri,
   moneyMinorToNumber,
   normalizeE164,
   parseAmountInput,
@@ -4259,6 +4895,7 @@ export {
   routingHint,
   signArtifact,
   signAuthorization,
+  signConsumerPaymentRequest,
   signOAC,
   signPartnerRequest,
   signPass,
@@ -4270,8 +4907,13 @@ export {
   verifyArtifactUri,
   verifyAuthorization,
   verifyClaimSignature,
+  verifyConsumerPaymentRequest,
+  verifyConsumerSettlement,
+  verifyConsumerSettlementReceiptQR,
   verifyOAC,
+  verifyOfflineSmsSettleToken,
   verifyPass,
+  verifyPayCardArtifact,
   verifyPaymentRequest,
   verifyReceipt,
   verifyRedemption,