@zkmedusa/passport-sdk 0.1.0

package/README.md

@@ -0,0 +1,113 @@
+# @zkmedusa/passport-sdk
+
+Use Medusa Passports in your app, presale, or whitelist without rebuilding verification logic.
+
+**Full documentation:** [zkmedusa.com/docs](https://www.zkmedusa.com/docs)
+
+## Install
+
+```bash
+npm install @zkmedusa/passport-sdk
+```
+
+## Quick start — verify locally
+
+```typescript
+import {
+  parsePassportJson,
+  verifyPassport,
+} from "@zkmedusa/passport-sdk";
+
+const passport = parsePassportJson(passportJsonFromUser);
+
+const result = verifyPassport(passport, {
+  issuerPublicKey: "749d6135f3d883950ff82f82bc2119e8b6e469ebfc4163dd10e1cc079b723565",
+  minTier: 2, // require SILVER+
+});
+
+if (result.valid) {
+  console.log(`Approved: ${result.tierLabel}`);
+} else {
+  console.log(result.errors);
+}
+```
+
+Fetch the issuer public key dynamically:
+
+```typescript
+import { MedusaPassportClient } from "@zkmedusa/passport-sdk";
+
+const client = new MedusaPassportClient({
+  baseUrl: "https://your-medusa-app.com",
+});
+
+const result = await client.verify(passport);
+```
+
+## Register for whitelist / presale
+
+Users present a passport, then link a **claim wallet** (the address that receives presale access).
+
+```typescript
+const client = new MedusaPassportClient({
+  baseUrl: "https://your-medusa-app.com",
+  apiKey: process.env.MEDUSA_PARTNER_API_KEY,
+});
+
+const registration = await client.register({
+  passport,
+  claimWallet: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
+  campaignId: "my-presale-q3",
+});
+
+console.log(registration.claimWallet, registration.tierLabel);
+```
+
+Pull the whitelist for your campaign:
+
+```typescript
+const entries = await client.getWhitelist("my-presale-q3");
+// [{ claimWallet, tier, tierLabel, nullifier, registeredAt }, ...]
+```
+
+## Partner API keys
+
+Medusa operators create keys in `.env`:
+
+```env
+MEDUSA_PARTNER_API_KEYS=my-presale-q3:sk_live_partner_key
+```
+
+Each key is scoped to one `campaignId`.
+
+## Endpoints used by the SDK
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /api/passport/issuer` | Issuer public key |
+| `GET /api/passport/verify` | Policy metadata |
+| `POST /api/passport/verify` | Remote passport verification |
+| `POST /api/partner/register` | Register passport + claim wallet |
+| `GET /api/partner/whitelist?campaignId=` | Export campaign whitelist |
+
+## Tier gating example
+
+```typescript
+const PRESALE_MIN_TIER = 1; // bronze
+const ALLOCATION_BY_TIER = { 1: 0.1, 2: 0.5, 3: 2 };
+
+const result = await client.verify(passport, { minTier: PRESALE_MIN_TIER });
+if (!result.valid) throw new Error("Not eligible");
+
+const maxSol = ALLOCATION_BY_TIER[result.tier!];
+```
+
+## Privacy model
+
+- The passport proves eligibility **without** revealing the proving wallet.
+- Registration links the passport to a **claim wallet** for whitelist/presale payout.
+- One passport nullifier can register once per campaign (anti-sybil).
+
+## Browser + Node
+
+The SDK works in Node.js, Next.js API routes, and the browser (local verify only).

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+import type { IssuerInfo, MedusaPassport, PassportPolicy, RegisterPassportInput, RegisterPassportResult, VerifyPassportOptions, VerifyPassportResult, WhitelistEntry } from "./types.js";
+export interface MedusaPassportClientOptions {
+    baseUrl: string;
+    apiKey?: string;
+    issuerPublicKey?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare class MedusaPassportClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private issuerPublicKey?;
+    private readonly fetchImpl;
+    constructor(options: MedusaPassportClientOptions);
+    fetchIssuer(): Promise<IssuerInfo>;
+    fetchPolicy(): Promise<PassportPolicy>;
+    verifyRemote(passport: MedusaPassport): Promise<VerifyPassportResult>;
+    verify(passport: MedusaPassport, options?: Omit<VerifyPassportOptions, "issuerPublicKey">): Promise<VerifyPassportResult>;
+    verifyLocal(passport: MedusaPassport, options: VerifyPassportOptions): VerifyPassportResult;
+    parseAndVerify(passportJson: string, options?: Omit<VerifyPassportOptions, "issuerPublicKey">): Promise<VerifyPassportResult>;
+    register(input: RegisterPassportInput): Promise<RegisterPassportResult>;
+    getWhitelist(campaignId: string): Promise<WhitelistEntry[]>;
+    hasValidSignature(passport: MedusaPassport, issuerPublicKey?: string): boolean;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,EAAE,2BAA2B;IAO1C,WAAW,IAAI,OAAO,CAAC,UAAU,CAAC;IAelC,WAAW,IAAI,OAAO,CAAC,cAAc,CAAC;IAUtC,YAAY,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA+BrE,MAAM,CACV,QAAQ,EAAE,cAAc,EACxB,OAAO,GAAE,IAAI,CAAC,qBAAqB,EAAE,iBAAiB,CAAM,GAC3D,OAAO,CAAC,oBAAoB,CAAC;IAehC,WAAW,CACT,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,qBAAqB,GAC7B,oBAAoB;IAIjB,cAAc,CAClB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,IAAI,CAAC,qBAAqB,EAAE,iBAAiB,CAAM,GAC3D,OAAO,CAAC,oBAAoB,CAAC;IAiB1B,QAAQ,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA+BvE,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAgCjE,iBAAiB,CAAC,QAAQ,EAAE,cAAc,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO;CAQ/E"}

package/dist/client.js

@@ -0,0 +1,118 @@
+import { MedusaPassportError } from "./errors.js";
+import { parsePassportJson, verifyPassport, verifyPassportSignature, } from "./verify.js";
+export class MedusaPassportClient {
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.apiKey = options.apiKey;
+        this.issuerPublicKey = options.issuerPublicKey;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async fetchIssuer() {
+        const response = await this.fetchImpl(`${this.baseUrl}/api/passport/issuer`);
+        if (!response.ok) {
+            throw new MedusaPassportError("Failed to fetch issuer public key.", "API_ERROR");
+        }
+        const issuer = (await response.json());
+        this.issuerPublicKey = issuer.publicKey;
+        return issuer;
+    }
+    async fetchPolicy() {
+        const response = await this.fetchImpl(`${this.baseUrl}/api/passport/verify`);
+        if (!response.ok) {
+            throw new MedusaPassportError("Failed to fetch passport policy.", "API_ERROR");
+        }
+        return response.json();
+    }
+    async verifyRemote(passport) {
+        const response = await this.fetchImpl(`${this.baseUrl}/api/passport/verify`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(passport),
+        });
+        const payload = (await response.json());
+        if (!response.ok || !payload.valid || !payload.passport) {
+            return {
+                valid: false,
+                errors: [payload.error ?? "Remote verification failed."],
+            };
+        }
+        return {
+            valid: true,
+            tier: payload.passport.statement.tier,
+            tierLabel: payload.tierLabel,
+            nullifier: payload.passport.nullifier,
+            expiresAt: payload.passport.expiresAt,
+            errors: [],
+        };
+    }
+    async verify(passport, options = {}) {
+        if (!this.issuerPublicKey) {
+            try {
+                await this.fetchIssuer();
+            }
+            catch {
+                return this.verifyRemote(passport);
+            }
+        }
+        return verifyPassport(passport, {
+            ...options,
+            issuerPublicKey: this.issuerPublicKey,
+        });
+    }
+    verifyLocal(passport, options) {
+        return verifyPassport(passport, options);
+    }
+    async parseAndVerify(passportJson, options = {}) {
+        const passport = parsePassportJson(passportJson);
+        if (!this.issuerPublicKey) {
+            await this.fetchIssuer().catch(() => undefined);
+        }
+        if (this.issuerPublicKey) {
+            return verifyPassport(passport, {
+                ...options,
+                issuerPublicKey: this.issuerPublicKey,
+            });
+        }
+        return this.verifyRemote(passport);
+    }
+    async register(input) {
+        if (!this.apiKey) {
+            throw new MedusaPassportError("apiKey is required to register passports.", "REGISTRATION_FAILED");
+        }
+        const response = await this.fetchImpl(`${this.baseUrl}/api/partner/register`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(input),
+        });
+        const payload = (await response.json());
+        if (!response.ok || !payload.registered) {
+            throw new MedusaPassportError(payload.error ?? "Passport registration failed.", "REGISTRATION_FAILED");
+        }
+        return payload;
+    }
+    async getWhitelist(campaignId) {
+        if (!this.apiKey) {
+            throw new MedusaPassportError("apiKey is required to fetch whitelist entries.", "API_ERROR");
+        }
+        const response = await this.fetchImpl(`${this.baseUrl}/api/partner/whitelist?campaignId=${encodeURIComponent(campaignId)}`, {
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+        });
+        const payload = (await response.json());
+        if (!response.ok) {
+            throw new MedusaPassportError(payload.error ?? "Failed to fetch whitelist.", "API_ERROR");
+        }
+        return payload.entries ?? [];
+    }
+    hasValidSignature(passport, issuerPublicKey) {
+        const key = issuerPublicKey ?? this.issuerPublicKey;
+        if (!key) {
+            return false;
+        }
+        return verifyPassportSignature(passport, key);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class MedusaPassportError extends Error {
+    readonly code: "INVALID_JSON" | "INVALID_PASSPORT" | "VERIFY_FAILED" | "API_ERROR" | "REGISTRATION_FAILED";
+    constructor(message: string, code: "INVALID_JSON" | "INVALID_PASSPORT" | "VERIFY_FAILED" | "API_ERROR" | "REGISTRATION_FAILED");
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,mBAAoB,SAAQ,KAAK;aAG1B,IAAI,EAChB,cAAc,GACd,kBAAkB,GAClB,eAAe,GACf,WAAW,GACX,qBAAqB;gBANzB,OAAO,EAAE,MAAM,EACC,IAAI,EAChB,cAAc,GACd,kBAAkB,GAClB,eAAe,GACf,WAAW,GACX,qBAAqB;CAK5B"}

package/dist/errors.js

@@ -0,0 +1,7 @@
+export class MedusaPassportError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "MedusaPassportError";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { MedusaPassportClient } from "./client.js";
+export type { MedusaPassportClientOptions } from "./client.js";
+export { MedusaPassportError } from "./errors.js";
+export { PASSPORT_POLICY_VERSION, PASSPORT_TIERS, TIER_LABELS, } from "./types.js";
+export type { IssuerInfo, MedusaPassport, PassportPolicy, PassportPublicInputs, PassportStatement, PassportTier, RegisterPassportInput, RegisterPassportResult, VerifyPassportOptions, VerifyPassportResult, WhitelistEntry, ZkProofBundle, } from "./types.js";
+export { hexToBytes, isValidSolanaAddress } from "./utils.js";
+export { parsePassportJson, verifyPassport, verifyPassportSignature, } from "./verify.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,uBAAuB,GACxB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { MedusaPassportClient } from "./client.js";
+export { MedusaPassportError } from "./errors.js";
+export { PASSPORT_POLICY_VERSION, PASSPORT_TIERS, TIER_LABELS, } from "./types.js";
+export { hexToBytes, isValidSolanaAddress } from "./utils.js";
+export { parsePassportJson, verifyPassport, verifyPassportSignature, } from "./verify.js";

package/dist/types.d.ts

@@ -0,0 +1,89 @@
+export declare const PASSPORT_POLICY_VERSION: "medusa-passport-v1";
+export declare const PASSPORT_TIERS: {
+    readonly BRONZE: 1;
+    readonly SILVER: 2;
+    readonly GOLD: 3;
+};
+export type PassportTier = (typeof PASSPORT_TIERS)[keyof typeof PASSPORT_TIERS];
+export declare const TIER_LABELS: Record<PassportTier, string>;
+export interface PassportPublicInputs {
+    current_timestamp: number;
+    min_age_seconds: number;
+    min_tx_count: number;
+    bronze_threshold: number;
+    silver_threshold: number;
+    gold_threshold: number;
+}
+export interface ZkProofBundle {
+    proofType: "noir_ultrahonk" | "dev_local";
+    proof: string;
+    publicInputs: string[];
+}
+export interface PassportStatement {
+    policyVersion: string;
+    tier: PassportTier;
+    tierLabel: string;
+    minWalletAgeDays: number;
+    minTransactionCount: number;
+    publicInputs: PassportPublicInputs;
+}
+export interface MedusaPassport {
+    type: "medusa_passport_v1";
+    chain: "solana";
+    statement: PassportStatement;
+    nullifier: string;
+    zkProof: ZkProofBundle;
+    issuedAt: string;
+    expiresAt: string;
+    issuer: "medusa";
+    signature: string;
+}
+export interface VerifyPassportOptions {
+    issuerPublicKey?: string;
+    minTier?: PassportTier;
+    policyVersion?: string;
+    now?: Date;
+}
+export interface VerifyPassportResult {
+    valid: boolean;
+    tier?: PassportTier;
+    tierLabel?: string;
+    nullifier?: string;
+    expiresAt?: string;
+    errors: string[];
+}
+export interface RegisterPassportInput {
+    passport: MedusaPassport;
+    claimWallet: string;
+    campaignId: string;
+}
+export interface RegisterPassportResult {
+    registered: boolean;
+    campaignId: string;
+    claimWallet: string;
+    tier: PassportTier;
+    tierLabel: string;
+    nullifier: string;
+    registeredAt: string;
+}
+export interface WhitelistEntry {
+    campaignId: string;
+    claimWallet: string;
+    tier: PassportTier;
+    tierLabel: string;
+    nullifier: string;
+    registeredAt: string;
+}
+export interface PassportPolicy {
+    policyVersion: string;
+    requirements: Record<string, unknown>;
+    validityDays: number;
+    issuePriceLamports: number;
+    devMode: boolean;
+}
+export interface IssuerInfo {
+    issuer: "medusa";
+    publicKey: string;
+    policyVersion: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,EAAG,oBAA6B,CAAC;AAErE,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEhF,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAIpD,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,gBAAgB,GAAG,WAAW,CAAC;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,oBAAoB,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,QAAQ,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,cAAc,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,QAAQ,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB"}

package/dist/types.js

@@ -0,0 +1,11 @@
+export const PASSPORT_POLICY_VERSION = "medusa-passport-v1";
+export const PASSPORT_TIERS = {
+    BRONZE: 1,
+    SILVER: 2,
+    GOLD: 3,
+};
+export const TIER_LABELS = {
+    [PASSPORT_TIERS.BRONZE]: "BRONZE",
+    [PASSPORT_TIERS.SILVER]: "SILVER",
+    [PASSPORT_TIERS.GOLD]: "GOLD",
+};

package/dist/utils.d.ts

@@ -0,0 +1,3 @@
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function isValidSolanaAddress(address: string): boolean;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAgBlD;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE7D"}

package/dist/utils.js

@@ -0,0 +1,14 @@
+export function hexToBytes(hex) {
+    const normalized = hex.startsWith("0x") ? hex.slice(2) : hex;
+    if (normalized.length % 2 !== 0) {
+        throw new Error("Invalid hex string.");
+    }
+    const bytes = new Uint8Array(normalized.length / 2);
+    for (let index = 0; index < bytes.length; index += 1) {
+        bytes[index] = Number.parseInt(normalized.slice(index * 2, index * 2 + 2), 16);
+    }
+    return bytes;
+}
+export function isValidSolanaAddress(address) {
+    return /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(address);
+}

package/dist/verify.d.ts

@@ -0,0 +1,5 @@
+import { type MedusaPassport, type VerifyPassportOptions, type VerifyPassportResult } from "./types.js";
+export declare function parsePassportJson(input: string): MedusaPassport;
+export declare function verifyPassportSignature(passport: MedusaPassport, issuerPublicKey: string): boolean;
+export declare function verifyPassport(passport: MedusaPassport, options?: VerifyPassportOptions): VerifyPassportResult;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAC;AAoBpB,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAc/D;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,cAAc,EACxB,eAAe,EAAE,MAAM,GACtB,OAAO,CAST;AAED,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,cAAc,EACxB,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CA8CtB"}

package/dist/verify.js

@@ -0,0 +1,69 @@
+import nacl from "tweetnacl";
+import { PASSPORT_POLICY_VERSION, TIER_LABELS, } from "./types.js";
+import { hexToBytes } from "./utils.js";
+function isPassportShape(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const passport = value;
+    return (passport.type === "medusa_passport_v1" &&
+        passport.chain === "solana" &&
+        passport.issuer === "medusa" &&
+        typeof passport.signature === "string" &&
+        typeof passport.nullifier === "string" &&
+        typeof passport.expiresAt === "string" &&
+        typeof passport.statement?.tier === "number");
+}
+export function parsePassportJson(input) {
+    let parsed;
+    try {
+        parsed = JSON.parse(input);
+    }
+    catch {
+        throw new Error("Passport JSON is invalid.");
+    }
+    if (!isPassportShape(parsed)) {
+        throw new Error("Passport structure is invalid.");
+    }
+    return parsed;
+}
+export function verifyPassportSignature(passport, issuerPublicKey) {
+    const { signature, ...payload } = passport;
+    const message = new TextEncoder().encode(JSON.stringify(payload));
+    return nacl.sign.detached.verify(message, hexToBytes(signature), hexToBytes(issuerPublicKey));
+}
+export function verifyPassport(passport, options = {}) {
+    const errors = [];
+    const policyVersion = options.policyVersion ?? PASSPORT_POLICY_VERSION;
+    const now = options.now ?? new Date();
+    if (passport.type !== "medusa_passport_v1") {
+        errors.push("Unsupported passport type.");
+    }
+    if (passport.statement.policyVersion !== policyVersion) {
+        errors.push("Passport policy version mismatch.");
+    }
+    if (new Date(passport.expiresAt).getTime() < now.getTime()) {
+        errors.push("Passport has expired.");
+    }
+    if (options.minTier && passport.statement.tier < options.minTier) {
+        errors.push(`Passport tier ${passport.statement.tier} is below required tier ${options.minTier}.`);
+    }
+    if (options.issuerPublicKey) {
+        const signatureValid = verifyPassportSignature(passport, options.issuerPublicKey);
+        if (!signatureValid) {
+            errors.push("Passport signature is invalid.");
+        }
+    }
+    else {
+        errors.push("issuerPublicKey is required for local verification.");
+    }
+    const valid = errors.length === 0;
+    return {
+        valid,
+        tier: passport.statement.tier,
+        tierLabel: TIER_LABELS[passport.statement.tier],
+        nullifier: passport.nullifier,
+        expiresAt: passport.expiresAt,
+        errors,
+    };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@zkmedusa/passport-sdk",
+  "version": "0.1.0",
+  "description": "Verify and register Medusa Passports in third-party apps, presales, and whitelists.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "homepage": "https://www.zkmedusa.com/docs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "tweetnacl": "^1.0.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  },
+  "keywords": [
+    "medusa",
+    "passport",
+    "solana",
+    "zk",
+    "whitelist",
+    "presale"
+  ]
+}