@nokinc-flur/sdk 2.1.0 → 2.3.0

package/dist/index.js

@@ -2961,7 +2961,17 @@ 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 ACCOUNT_FUNDED_OAC_MAX_TTL_MS = 1e3 * 60 * 60 * 24;
+var IssuerTrustKeySchema = z13.object({
+  issuerId: z13.string().min(1).max(128),
+  alg: z13.literal("p256"),
+  publicKeySpkiB64: Base64Std3.min(64).max(4096),
+  notBeforeMs: z13.number().int().nonnegative().optional(),
+  notAfterMs: z13.number().int().positive().optional()
+});
+var IssuerTrustBundleSchema = z13.object({
+  keys: z13.array(IssuerTrustKeySchema).min(1)
+});
 var CONSUMER_OFFLINE_CLAIM_SUBMIT_GRACE_MS = 1e3 * 60 * 60 * 24;
 var AttestationSecurityLevelSchema = z13.enum([
   "STRONGBOX",
@@ -3015,13 +3025,28 @@ var ConsumerOACSchema = z13.object({
   alg: z13.literal("p256"),
   /** P-256 SubjectPublicKeyInfo DER, base64. */
   devicePubkeySpkiB64: Base64Std3.min(64).max(4096),
-  perTxCapKobo: z13.number().int().positive(),
-  cumulativeCapKobo: z13.number().int().positive(),
+  /**
+   * Per-transaction / cumulative offline spend ceilings. Zero is valid and
+   * denotes an identity-only OAC: the credential proves who the holder is and
+   * binds their device key for offline-verifiable first contact, but carries
+   * no offline spend authority (every claim against it routes to REVIEW).
+   * Issued to zero-balance wallets so they can still be paid offline.
+   */
+  perTxCapKobo: z13.number().int().nonnegative(),
+  cumulativeCapKobo: z13.number().int().nonnegative(),
   currency: z13.string().length(3),
   validFromMs: z13.number().int().nonnegative(),
   validUntilMs: z13.number().int().nonnegative(),
   counterSeed: z13.number().int().nonnegative(),
-  issuedAtMs: z13.number().int().nonnegative()
+  issuedAtMs: z13.number().int().nonnegative(),
+  /**
+   * Issuer-attested identity folded into the OAC so a single signed
+   * credential serves both Tier B offline-verifiable identity and offline
+   * spend authority. Verified offline against a pinned issuer key; the
+   * backend remains authoritative at settlement.
+   */
+  phoneE164: z13.string().regex(/^\+[1-9]\d{7,14}$/),
+  displayName: z13.string().min(1).max(64)
 });
 var SignedConsumerOACSchema = z13.object({
   oac: ConsumerOACSchema,
@@ -3189,6 +3214,12 @@ function createMeOfflineClient(opts) {
       `/v1/me/offline/settlements/${encodeURIComponent(idOrKey)}`,
       void 0,
       (raw) => ConsumerSettlementSchema.parse(raw)
+    ),
+    getIssuerKeys: () => call(
+      "GET",
+      "/v1/issuer/keys",
+      void 0,
+      (raw) => IssuerTrustBundleSchema.parse(raw)
     )
   };
 }
@@ -3549,13 +3580,101 @@ function base64UrlDecodeUtf8(input) {
   throw new Error("base64 decoder unavailable");
 }
 
+// src/me-offline/oac.ts
+var CONSUMER_OAC_DOMAIN = "flur:consumer-offline:v1:oac";
+function consumerOacSigningPayload(oac) {
+  return { domain: CONSUMER_OAC_DOMAIN, ...oac };
+}
+function verifyOacOffline(signed, trustedKeys, options = {}) {
+  const parsed = SignedConsumerOACSchema.safeParse(signed);
+  if (!parsed.success) return { ok: false, reason: "malformed" };
+  const oacParsed = ConsumerOACSchema.safeParse(parsed.data.oac);
+  if (!oacParsed.success) return { ok: false, reason: "malformed" };
+  const oac = oacParsed.data;
+  const nowMs = options.nowMs ?? Date.now();
+  const pinned = trustedKeys.filter(
+    (k) => k.issuerId === oac.issuerId && (k.notBeforeMs === void 0 || nowMs >= k.notBeforeMs) && (k.notAfterMs === void 0 || nowMs <= k.notAfterMs)
+  );
+  if (pinned.length === 0) return { ok: false, reason: "untrusted_issuer" };
+  const signingBytes = canonicalJSONBytes(consumerOacSigningPayload(oac));
+  const signatureOk = pinned.some(
+    (k) => verifyIssuerP256(signingBytes, parsed.data.issuerSig, k.publicKeySpkiB64)
+  );
+  if (!signatureOk) return { ok: false, reason: "signature_invalid" };
+  if (oac.validUntilMs - oac.validFromMs > ACCOUNT_FUNDED_OAC_MAX_TTL_MS) {
+    return { ok: false, reason: "window_too_long" };
+  }
+  if (nowMs < oac.validFromMs) return { ok: false, reason: "not_yet_valid" };
+  if (nowMs >= oac.validUntilMs) return { ok: false, reason: "expired" };
+  return {
+    ok: true,
+    oac,
+    identity: {
+      oacId: oac.oacId,
+      issuerId: oac.issuerId,
+      userId: oac.userId,
+      phoneE164: oac.phoneE164,
+      displayName: oac.displayName,
+      devicePubkeySpkiB64: oac.devicePubkeySpkiB64
+    }
+  };
+}
+var CONSUMER_OAC_QR_PREFIX = "FLUROAC1.";
+function isConsumerOacQR(value) {
+  return value.startsWith(CONSUMER_OAC_QR_PREFIX);
+}
+function encodeConsumerOacQR(signed) {
+  const parsed = SignedConsumerOACSchema.parse(signed);
+  return `${CONSUMER_OAC_QR_PREFIX}${base64UrlEncodeUtf82(JSON.stringify(parsed))}`;
+}
+function decodeUnverifiedConsumerOacQR(value) {
+  if (!value.startsWith(CONSUMER_OAC_QR_PREFIX)) {
+    throw new Error("not a Flur consumer OAC QR");
+  }
+  const encoded = value.slice(CONSUMER_OAC_QR_PREFIX.length);
+  let raw;
+  try {
+    raw = JSON.parse(base64UrlDecodeUtf82(encoded));
+  } catch {
+    throw new Error("consumer OAC QR is malformed");
+  }
+  return SignedConsumerOACSchema.parse(raw);
+}
+function base64UrlEncodeUtf82(input) {
+  const bytes = new TextEncoder().encode(input);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  const base64 = typeof btoa === "function" ? btoa(binary) : typeof Buffer !== "undefined" ? Buffer.from(bytes).toString("base64") : void 0;
+  if (!base64) throw new Error("base64 encoder unavailable");
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function base64UrlDecodeUtf82(input) {
+  const base64 = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64.padEnd(
+    base64.length + (4 - base64.length % 4) % 4,
+    "="
+  );
+  if (typeof atob === "function") {
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index++) {
+      bytes[index] = binary.charCodeAt(index);
+    }
+    return new TextDecoder().decode(bytes);
+  }
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(padded, "base64").toString("utf8");
+  }
+  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(
+  return `${OFFLINE_CLAIM_SMS_PREFIX}${base64UrlEncodeUtf83(
     JSON.stringify(parsed)
   )}`;
 }
@@ -3565,7 +3684,7 @@ function decodeOfflineClaimSmsMessage(message) {
   const encoded = token.slice(OFFLINE_CLAIM_SMS_PREFIX.length);
   let raw;
   try {
-    raw = JSON.parse(base64UrlDecodeUtf82(encoded));
+    raw = JSON.parse(base64UrlDecodeUtf83(encoded));
   } catch {
     throw new Error("offline claim QR token is malformed");
   }
@@ -3791,10 +3910,10 @@ function bytesToBase64Url(bytes) {
   }
   return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
 }
-function base64UrlEncodeUtf82(input) {
+function base64UrlEncodeUtf83(input) {
   return bytesToBase64Url(utf8(input));
 }
-function base64UrlDecodeUtf82(input) {
+function base64UrlDecodeUtf83(input) {
   return new TextDecoder().decode(base64UrlToBytes(input));
 }
 function base64UrlToBytes(input) {
@@ -4294,7 +4413,10 @@ 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) => z17.string().regex(
   new RegExp(`^[0-9a-fA-F]{${length * 2}}$`),
@@ -4432,6 +4554,12 @@ var IdentityArtifactSchema = z17.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,
@@ -4443,7 +4571,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,
@@ -4456,7 +4585,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);
@@ -4541,6 +4671,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,
@@ -4556,6 +4810,8 @@ export {
   CLAIM_DOMAIN_V2,
   COLLECTION_INTENT_STATUSES,
   COLLECTION_PAYMENT_STATUSES,
+  CONSUMER_OAC_DOMAIN,
+  CONSUMER_OAC_QR_PREFIX,
   CONSUMER_OFFLINE_CLAIM_SUBMIT_GRACE_MS,
   CONSUMER_PAYMENT_REQUEST_DOMAIN,
   CONSUMER_SETTLEMENT_DOMAIN,
@@ -4594,6 +4850,8 @@ export {
   IdentityArtifactSchema,
   IngestFundingResultSchema,
   IssueAccountOacInputSchema,
+  IssuerTrustBundleSchema,
+  IssuerTrustKeySchema,
   LedgerJournalEntryArtifactSchema,
   ListPayoutDestinationsResultSchema,
   MEMBERSHIP_ROLES,
@@ -4634,6 +4892,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,
@@ -4641,6 +4902,7 @@ export {
   PassArtifactSchema,
   PassMetadataSchema,
   PassSchema,
+  PayCardArtifactSchema,
   PayCollectionInputSchema,
   PaymentClaimSchema,
   PaymentIntentArtifactSchema,
@@ -4679,6 +4941,7 @@ export {
   buildConsumerPaymentRequest,
   buildOAC,
   buildPass,
+  buildPayCardSigningInput,
   buildPaymentRequest,
   buildReceipt,
   buildRedemption,
@@ -4692,6 +4955,7 @@ export {
   computeConsumerClaimEncounterId,
   computeEncounterId,
   constantTimeEqual,
+  consumerOacSigningPayload,
   consumerPaymentRequestSigningBytes,
   consumerPaymentRequestSigningPayload,
   consumerSettlementSigningPayload,
@@ -4712,6 +4976,7 @@ export {
   createPartnerFundingClient,
   createPartnerProfileAdminClient,
   createPassesClient,
+  createPayCardArtifactUri,
   createReceiptArtifactUri,
   createReceiptsClient,
   createSoftwareP256Signer,
@@ -4721,12 +4986,15 @@ export {
   decodeConsumerSettlementReceiptQR,
   decodeOfflineClaimSmsMessage,
   decodeOfflineSmsSettleToken,
+  decodePayCardArtifact,
   decodePaymentRequestQR,
+  decodeUnverifiedConsumerOacQR,
   decodeUnverifiedConsumerSettlementReceiptQR,
   derToRawP256Signature,
   encodeArtifactUri,
   encodeAuthorizationQR,
   encodeBase45,
+  encodeConsumerOacQR,
   encodeConsumerSettlementReceiptQR,
   encodeNQR,
   encodeOfflineClaimSmsMessage,
@@ -4738,10 +5006,13 @@ export {
   generateDynamicQR,
   generateStaticQR,
   init,
+  inspectPayCardFreshness,
+  isConsumerOacQR,
   isConsumerPaymentRequestExpired,
   isHardenedArtifactType,
   isKnownArtifactType,
   isPassWithinValidity,
+  isPayCardArtifactUri,
   moneyMinorToNumber,
   normalizeE164,
   parseAmountInput,
@@ -4767,8 +5038,10 @@ export {
   verifyConsumerSettlement,
   verifyConsumerSettlementReceiptQR,
   verifyOAC,
+  verifyOacOffline,
   verifyOfflineSmsSettleToken,
   verifyPass,
+  verifyPayCardArtifact,
   verifyPaymentRequest,
   verifyReceipt,
   verifyRedemption,