@nokinc-flur/sdk 2.1.0 → 2.2.0

package/dist/index.cjs

@@ -122,6 +122,9 @@ __export(index_exports, {
   PASS_STATES: () => PASS_STATES,
   PAYLOAD_FORMAT_INDICATOR_VALUE: () => PAYLOAD_FORMAT_INDICATOR_VALUE,
   PAYOUT_DESTINATION_STATUSES: () => PAYOUT_DESTINATION_STATUSES,
+  PAY_CARD_DEFAULT_TTL_MS: () => PAY_CARD_DEFAULT_TTL_MS,
+  PAY_CARD_REFRESH_THRESHOLD_MS: () => PAY_CARD_REFRESH_THRESHOLD_MS,
+  PAY_CARD_URI_PREFIX: () => PAY_CARD_URI_PREFIX,
   POINT_OF_INITIATION: () => POINT_OF_INITIATION,
   PartnerFundingEventInputSchema: () => PartnerFundingEventInputSchema,
   PartnerFundingSchema: () => PartnerFundingSchema,
@@ -129,6 +132,7 @@ __export(index_exports, {
   PassArtifactSchema: () => PassArtifactSchema,
   PassMetadataSchema: () => PassMetadataSchema,
   PassSchema: () => PassSchema,
+  PayCardArtifactSchema: () => PayCardArtifactSchema,
   PayCollectionInputSchema: () => PayCollectionInputSchema,
   PaymentClaimSchema: () => PaymentClaimSchema,
   PaymentIntentArtifactSchema: () => PaymentIntentArtifactSchema,
@@ -167,6 +171,7 @@ __export(index_exports, {
   buildConsumerPaymentRequest: () => buildConsumerPaymentRequest,
   buildOAC: () => buildOAC,
   buildPass: () => buildPass,
+  buildPayCardSigningInput: () => buildPayCardSigningInput,
   buildPaymentRequest: () => buildPaymentRequest,
   buildReceipt: () => buildReceipt,
   buildRedemption: () => buildRedemption,
@@ -200,6 +205,7 @@ __export(index_exports, {
   createPartnerFundingClient: () => createPartnerFundingClient,
   createPartnerProfileAdminClient: () => createPartnerProfileAdminClient,
   createPassesClient: () => createPassesClient,
+  createPayCardArtifactUri: () => createPayCardArtifactUri,
   createReceiptArtifactUri: () => createReceiptArtifactUri,
   createReceiptsClient: () => createReceiptsClient,
   createSoftwareP256Signer: () => createSoftwareP256Signer,
@@ -209,6 +215,7 @@ __export(index_exports, {
   decodeConsumerSettlementReceiptQR: () => decodeConsumerSettlementReceiptQR,
   decodeOfflineClaimSmsMessage: () => decodeOfflineClaimSmsMessage,
   decodeOfflineSmsSettleToken: () => decodeOfflineSmsSettleToken,
+  decodePayCardArtifact: () => decodePayCardArtifact,
   decodePaymentRequestQR: () => decodePaymentRequestQR,
   decodeUnverifiedConsumerSettlementReceiptQR: () => decodeUnverifiedConsumerSettlementReceiptQR,
   derToRawP256Signature: () => derToRawP256Signature,
@@ -226,10 +233,12 @@ __export(index_exports, {
   generateDynamicQR: () => generateDynamicQR,
   generateStaticQR: () => generateStaticQR,
   init: () => init,
+  inspectPayCardFreshness: () => inspectPayCardFreshness,
   isConsumerPaymentRequestExpired: () => isConsumerPaymentRequestExpired,
   isHardenedArtifactType: () => isHardenedArtifactType,
   isKnownArtifactType: () => isKnownArtifactType,
   isPassWithinValidity: () => isPassWithinValidity,
+  isPayCardArtifactUri: () => isPayCardArtifactUri,
   moneyMinorToNumber: () => moneyMinorToNumber,
   normalizeE164: () => normalizeE164,
   parseAmountInput: () => parseAmountInput,
@@ -257,6 +266,7 @@ __export(index_exports, {
   verifyOAC: () => verifyOAC,
   verifyOfflineSmsSettleToken: () => verifyOfflineSmsSettleToken,
   verifyPass: () => verifyPass,
+  verifyPayCardArtifact: () => verifyPayCardArtifact,
   verifyPaymentRequest: () => verifyPaymentRequest,
   verifyReceipt: () => verifyReceipt,
   verifyRedemption: () => verifyRedemption,
@@ -4561,7 +4571,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) => import_zod17.z.string().regex(
   new RegExp(`^[0-9a-fA-F]{${length * 2}}$`),
@@ -4699,6 +4712,12 @@ var IdentityArtifactSchema = import_zod17.z.object({
   claimValueHash: HexString(32),
   attestedAtMs: PositiveInt
 });
+var PayCardArtifactSchema = import_zod17.z.object({
+  userId: ShortId,
+  phoneE164: import_zod17.z.string().regex(/^\+[1-9]\d{7,14}$/, "phoneE164 must be normalised E.164"),
+  displayName: import_zod17.z.string().min(1).max(64),
+  devicePubKeySpkiB64: import_zod17.z.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,
@@ -4710,7 +4729,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,
@@ -4723,7 +4743,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);
@@ -4808,6 +4829,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) };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACCOUNT_FUNDED_OAC_MAX_TTL_MS,
@@ -4902,6 +5047,9 @@ function createOfflinePaymentAuthorizationArtifactUri(input) {
   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,
@@ -4909,6 +5057,7 @@ function createOfflinePaymentAuthorizationArtifactUri(input) {
   PassArtifactSchema,
   PassMetadataSchema,
   PassSchema,
+  PayCardArtifactSchema,
   PayCollectionInputSchema,
   PaymentClaimSchema,
   PaymentIntentArtifactSchema,
@@ -4947,6 +5096,7 @@ function createOfflinePaymentAuthorizationArtifactUri(input) {
   buildConsumerPaymentRequest,
   buildOAC,
   buildPass,
+  buildPayCardSigningInput,
   buildPaymentRequest,
   buildReceipt,
   buildRedemption,
@@ -4980,6 +5130,7 @@ function createOfflinePaymentAuthorizationArtifactUri(input) {
   createPartnerFundingClient,
   createPartnerProfileAdminClient,
   createPassesClient,
+  createPayCardArtifactUri,
   createReceiptArtifactUri,
   createReceiptsClient,
   createSoftwareP256Signer,
@@ -4989,6 +5140,7 @@ function createOfflinePaymentAuthorizationArtifactUri(input) {
   decodeConsumerSettlementReceiptQR,
   decodeOfflineClaimSmsMessage,
   decodeOfflineSmsSettleToken,
+  decodePayCardArtifact,
   decodePaymentRequestQR,
   decodeUnverifiedConsumerSettlementReceiptQR,
   derToRawP256Signature,
@@ -5006,10 +5158,12 @@ function createOfflinePaymentAuthorizationArtifactUri(input) {
   generateDynamicQR,
   generateStaticQR,
   init,
+  inspectPayCardFreshness,
   isConsumerPaymentRequestExpired,
   isHardenedArtifactType,
   isKnownArtifactType,
   isPassWithinValidity,
+  isPayCardArtifactUri,
   moneyMinorToNumber,
   normalizeE164,
   parseAmountInput,
@@ -5037,6 +5191,7 @@ function createOfflinePaymentAuthorizationArtifactUri(input) {
   verifyOAC,
   verifyOfflineSmsSettleToken,
   verifyPass,
+  verifyPayCardArtifact,
   verifyPaymentRequest,
   verifyReceipt,
   verifyRedemption,