@solgate/server 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Solana Allowlist contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/app-CB9x11xM.d.ts

@@ -0,0 +1,415 @@
+import * as _solgate_core from '@solgate/core';
+import { Campaign, Entry, ModuleRegistry, Requirement, RequirementResult, AllowlistEvent, AllowlistEventType } from '@solgate/core';
+import * as hono_types from 'hono/types';
+import { Context, Hono } from 'hono';
+
+interface SocialLink {
+    campaignId: string;
+    provider: string;
+    providerUserId: string;
+    wallet: string;
+    handle?: string;
+    meta?: Record<string, unknown>;
+    createdAt: number;
+}
+interface Webhook {
+    id: string;
+    url: string;
+    secret: string;
+    events: string[];
+    campaignId?: string;
+    active: boolean;
+    createdAt: number;
+}
+interface WebhookDelivery {
+    id: string;
+    webhookId: string;
+    eventId: string;
+    status: number;
+    attempts: number;
+    lastError?: string;
+    createdAt: number;
+}
+/** Immutable eligibility snapshot taken before a mint. */
+interface Snapshot {
+    id: string;
+    campaignId: string;
+    createdAt: number;
+    count: number;
+    totalAllocation: number;
+    merkle?: {
+        scheme: string;
+        root: string;
+    };
+    /** wallet → { allocation, rank, proof } */
+    entries: Record<string, {
+        allocation: number;
+        rank: number;
+        proof?: string[];
+    }>;
+}
+interface ApiKey {
+    id: string;
+    hash: string;
+    label: string;
+    scopes: ("admin" | "read")[];
+    createdAt: number;
+}
+/**
+ * Storage adapter. Every method is async so the same interface works for
+ * in-memory, SQLite, Postgres, D1, KV, etc. Keep it small on purpose.
+ */
+interface Storage {
+    getCampaign(id: string): Promise<Campaign | null>;
+    listCampaigns(): Promise<Campaign[]>;
+    putCampaign(c: Campaign): Promise<void>;
+    deleteCampaign(id: string): Promise<void>;
+    getEntry(campaignId: string, wallet: string): Promise<Entry | null>;
+    putEntry(e: Entry): Promise<void>;
+    listEntries(campaignId: string, opts?: {
+        eligibleOnly?: boolean;
+        offset?: number;
+        limit?: number;
+    }): Promise<Entry[]>;
+    countEntries(campaignId: string, opts?: {
+        eligibleOnly?: boolean;
+    }): Promise<number>;
+    findEntryByReferralCode(campaignId: string, code: string): Promise<Entry | null>;
+    setTemp(key: string, value: string, ttlSeconds: number): Promise<void>;
+    getTemp(key: string): Promise<string | null>;
+    deleteTemp(key: string): Promise<void>;
+    /** ATOMIC increment with TTL (rate limits, attempt counters, referral caps). Must be safe under concurrency. */
+    incrTemp(key: string, ttlSeconds: number): Promise<number>;
+    getSocialLink(campaignId: string, provider: string, providerUserId: string): Promise<SocialLink | null>;
+    /**
+     * ATOMIC "insert if absent". Returns `{ ok: true }` when this wallet now owns the identity
+     * (fresh insert or already owned by the same wallet), otherwise `{ ok: false, owner }`.
+     * The database's unique constraint — not application sequencing — enforces one-identity-one-wallet.
+     */
+    claimSocialLink(link: SocialLink): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        owner: string;
+    }>;
+    listSocialLinksForWallet(campaignId: string, wallet: string): Promise<SocialLink[]>;
+    putSnapshot(s: Snapshot): Promise<void>;
+    getSnapshot(campaignId: string, id?: string): Promise<Snapshot | null>;
+    listSnapshots(campaignId: string): Promise<Omit<Snapshot, "entries">[]>;
+    listWebhooks(): Promise<Webhook[]>;
+    putWebhook(w: Webhook): Promise<void>;
+    deleteWebhook(id: string): Promise<void>;
+    putDelivery(d: WebhookDelivery): Promise<void>;
+    listApiKeys(): Promise<ApiKey[]>;
+    putApiKey(k: ApiKey): Promise<void>;
+    deleteApiKey(id: string): Promise<void>;
+}
+
+interface OAuthClient {
+    clientId: string;
+    clientSecret: string;
+}
+interface ServerConfig {
+    storage: Storage;
+    /** Public origin of this API, e.g. https://api.myproject.xyz — used for OAuth callbacks. */
+    baseUrl: string;
+    /** Domain shown in the sign-in message (defaults to hostname of baseUrl). */
+    domain?: string;
+    /** Origins allowed to embed the widget. */
+    corsOrigins?: string[] | "*";
+    /** 32+ byte secret for signing sessions. */
+    sessionSecret: string;
+    sessionTtlSeconds?: number;
+    /** Bootstrap admin key. Additional keys can be created via API. */
+    adminApiKey?: string;
+    /**
+     * Public eligibility lookup (`GET /campaigns/:id/eligibility/:wallet`) exposure:
+     *  - "minimal" (default): anyone can read { eligible, allocation, merkle proof } — what a mint page needs.
+     *  - "full": also points and rank without a key.
+     *  - "protected": requires a read API key for everything.
+     */
+    eligibilityLookup?: "minimal" | "full" | "protected";
+    /**
+     * Which header carries the real client IP. Only trust headers your reverse
+     * proxy overwrites, otherwise rate limits can be bypassed by spoofing.
+     *  - "none" (default): use the socket address supplied via `getClientIp`, else no per-IP limiting
+     *  - "cloudflare": cf-connecting-ip
+     *  - "x-forwarded-for": first hop of x-forwarded-for (nginx, Vercel, Railway, Fly)
+     */
+    trustProxy?: "none" | "cloudflare" | "x-forwarded-for";
+    /** Runtime-specific socket address resolver (e.g. @hono/node-server's getConnInfo). */
+    getClientIp?: (req: Request) => string | undefined;
+    /** Origins the OAuth flow may redirect back to, in addition to baseUrl and corsOrigins. */
+    allowedReturnOrigins?: string[];
+    /** Allow http:// webhook targets (development only). */
+    allowInsecureWebhooks?: boolean;
+    solana: {
+        rpcUrl: string;
+        /** DAS-compatible endpoint (Helius, Triton, QuickNode…) for NFT lookups. Defaults to rpcUrl. */
+        dasUrl?: string;
+    };
+    oauth?: {
+        x?: OAuthClient;
+        discord?: OAuthClient & {
+            botToken?: string;
+        };
+        google?: OAuthClient;
+    };
+    telegram?: {
+        botToken: string;
+        botUsername: string;
+    };
+    captcha?: {
+        turnstileSecret?: string;
+        hcaptchaSecret?: string;
+        recaptchaSecret?: string;
+    };
+    /** Custom modules & verifiers. */
+    registry?: ModuleRegistry;
+    verifiers?: Verifier[];
+    rateLimit?: {
+        windowSeconds: number;
+        max: number;
+    };
+}
+declare function normalizeConfig(cfg: ServerConfig): {
+    domain: string;
+    sessionTtlSeconds: number;
+    corsOrigins: string[] | "*";
+    eligibilityLookup: "minimal" | "full" | "protected";
+    trustProxy: "none" | "cloudflare" | "x-forwarded-for";
+    rateLimit: {
+        windowSeconds: number;
+        max: number;
+    };
+    solana: {
+        dasUrl: string;
+        rpcUrl: string;
+    };
+    storage: Storage;
+    /** Public origin of this API, e.g. https://api.myproject.xyz — used for OAuth callbacks. */
+    baseUrl: string;
+    /** 32+ byte secret for signing sessions. */
+    sessionSecret: string;
+    /** Bootstrap admin key. Additional keys can be created via API. */
+    adminApiKey?: string;
+    /** Runtime-specific socket address resolver (e.g. @hono/node-server's getConnInfo). */
+    getClientIp?: (req: Request) => string | undefined;
+    /** Origins the OAuth flow may redirect back to, in addition to baseUrl and corsOrigins. */
+    allowedReturnOrigins?: string[];
+    /** Allow http:// webhook targets (development only). */
+    allowInsecureWebhooks?: boolean;
+    oauth?: {
+        x?: OAuthClient;
+        discord?: OAuthClient & {
+            botToken?: string;
+        };
+        google?: OAuthClient;
+    };
+    telegram?: {
+        botToken: string;
+        botUsername: string;
+    };
+    captcha?: {
+        turnstileSecret?: string;
+        hcaptchaSecret?: string;
+        recaptchaSecret?: string;
+    };
+    /** Custom modules & verifiers. */
+    registry?: ModuleRegistry;
+    verifiers?: Verifier[];
+};
+type NormalizedConfig = ReturnType<typeof normalizeConfig>;
+
+interface VerifyContext<TConfig = unknown, TInput = unknown> {
+    campaign: Campaign;
+    requirement: Requirement<TConfig>;
+    config: TConfig;
+    wallet: string;
+    entry: Entry;
+    /** Client-supplied payload (quiz answers, captcha token, referral code, oauth profile…). */
+    input: TInput;
+    storage: Storage;
+    cfg: NormalizedConfig;
+    /** Request metadata for rate limiting / audit. */
+    ip?: string;
+}
+interface Verifier<TConfig = unknown, TInput = unknown> {
+    moduleId: string;
+    verify(ctx: VerifyContext<TConfig, TInput>): Promise<RequirementResult>;
+    /** Optional: return public config safe for the browser (e.g. strip quiz answers). */
+    publicConfig?(config: TConfig): unknown;
+}
+declare const pass: (key: string, module: string, evidence?: Record<string, unknown>) => RequirementResult;
+declare const fail: (key: string, module: string, reason: string, evidence?: Record<string, unknown>) => RequirementResult;
+/**
+ * Throw this when an upstream dependency (RPC, provider API) failed. The
+ * service leaves the entry untouched and returns HTTP 503 to the client, so
+ * the user can retry — instead of persisting a false "failed" result.
+ */
+declare class VerificationUnavailable extends Error {
+    readonly code = "verification_unavailable";
+}
+
+/**
+ * Webhook dispatcher. Payloads are signed with HMAC-SHA256 over
+ * `${timestamp}.${body}` in the `X-Allowlist-Signature` header
+ * ("t=<ts>,v1=<hex>"), so receivers can verify + reject replays.
+ */
+declare class EventBus {
+    private storage;
+    private waitUntil?;
+    private listeners;
+    constructor(storage: Storage, waitUntil?: ((p: Promise<unknown>) => void) | undefined);
+    on(fn: (e: AllowlistEvent) => void | Promise<void>): () => ((e: AllowlistEvent) => void | Promise<void>)[];
+    emit<T>(type: AllowlistEventType, campaignId: string, data: T, wallet?: string): Promise<AllowlistEvent<T>>;
+    private dispatch;
+    deliver(webhookId: string, url: string, secret: string, event: AllowlistEvent, maxAttempts?: number): Promise<void>;
+}
+/** Helper for receivers (Next.js API route, Express, etc). */
+declare function verifyWebhookSignature(secret: string, header: string, body: string, toleranceSeconds?: number): boolean;
+
+declare class AllowlistError extends Error {
+    status: number;
+    code: string;
+    constructor(status: number, message: string, code?: string);
+}
+/** Framework-agnostic business logic. Routes are thin wrappers over this. */
+declare class AllowlistService {
+    cfg: NormalizedConfig;
+    registry: ModuleRegistry;
+    verifiers: Map<string, Verifier<unknown, unknown>>;
+    events: EventBus;
+    constructor(cfg: NormalizedConfig, waitUntil?: (p: Promise<unknown>) => void);
+    getCampaign(id: string): Promise<Campaign>;
+    saveCampaign(input: unknown): Promise<Campaign>;
+    /**
+     * Campaign as seen by the browser. Requirement config is PRIVATE BY DEFAULT:
+     * a module must opt in via `publicConfig` (on its definition, or on the
+     * verifier) to expose anything. Custom modules that forget get `{}`, not
+     * their secrets.
+     */
+    publicCampaign(c: Campaign): {
+        requirements: {
+            config: {};
+            category: "input" | "onchain" | "social" | "custom";
+            label: string;
+            key: string;
+            module: string;
+            required?: boolean;
+            points?: number;
+            title?: string;
+            description?: string;
+        }[];
+        minPoints: number;
+        allocation: {
+            flat: number;
+            mode: "flat" | "tiered" | "per-requirement";
+            tiers: {
+                minPoints: number;
+                allocation: number;
+                label?: string | undefined;
+            }[];
+            perRequirement: Record<string, number>;
+            maxPerWallet?: number | undefined;
+            totalSupply?: number | undefined;
+        };
+        type: "custom" | "nft-mint" | "token-launch" | "presale" | "community";
+        id: string;
+        name: string;
+        cluster: "mainnet-beta" | "devnet" | "testnet";
+        merkle: {
+            enabled: boolean;
+            scheme: "candy-guard" | "sha256-sorted";
+        };
+        metadata: Record<string, unknown>;
+        description?: string | undefined | undefined;
+        startsAt?: string | undefined | undefined;
+        endsAt?: string | undefined | undefined;
+        maxEntries?: number | undefined | undefined;
+        createdAt?: string | undefined | undefined;
+        updatedAt?: string | undefined | undefined;
+    };
+    getOrCreateEntry(c: Campaign, wallet: string): Promise<Entry>;
+    private uniqueReferralCode;
+    /** Run one requirement's verifier and persist the result. */
+    verifyRequirement(c: Campaign, wallet: string, key: string, input: unknown, ip?: string): Promise<{
+        entry: Entry;
+        result: RequirementResult;
+    }>;
+    /** Re-run all recheckable (on-chain) requirements for every entry — e.g. snapshot before mint. */
+    recheckCampaign(c: Campaign, onlyWallets?: string[]): Promise<{
+        checked: number;
+        changed: number;
+        unavailable: number;
+    }>;
+    /**
+     * Freeze the current eligible set (with caps applied) into an immutable
+     * snapshot: root, per-wallet allocation/rank/proof. Serve mint-time lookups
+     * from this so the root can't drift while people are minting.
+     */
+    createSnapshot(c: Campaign): Promise<Snapshot>;
+    /** Entries with campaign-wide caps applied (ranked FCFS). */
+    finalEntries(c: Campaign): Promise<Entry[]>;
+    /** Admin override for a single requirement (approve social task, manual pass/fail). */
+    overrideRequirement(c: Campaign, wallet: string, key: string, passed: boolean, note?: string): Promise<Entry>;
+}
+
+type AppEnv = {
+    Variables: {
+        session: {
+            wallet: string;
+            campaignId: string;
+        };
+        apiKeyScopes: string[];
+    };
+};
+declare function createAllowlistApp(config: ServerConfig, opts?: {
+    waitUntil?: (p: Promise<unknown>) => void;
+    getClientIp?: (c: Context) => string | undefined;
+}): {
+    app: Hono<AppEnv, hono_types.BlankSchema, "/">;
+    service: AllowlistService;
+    config: {
+        domain: string;
+        sessionTtlSeconds: number;
+        corsOrigins: string[] | "*";
+        eligibilityLookup: "minimal" | "full" | "protected";
+        trustProxy: "none" | "cloudflare" | "x-forwarded-for";
+        rateLimit: {
+            windowSeconds: number;
+            max: number;
+        };
+        solana: {
+            dasUrl: string;
+            rpcUrl: string;
+        };
+        storage: Storage;
+        baseUrl: string;
+        sessionSecret: string;
+        adminApiKey?: string;
+        getClientIp?: (req: Request) => string | undefined;
+        allowedReturnOrigins?: string[];
+        allowInsecureWebhooks?: boolean;
+        oauth?: {
+            x?: OAuthClient;
+            discord?: OAuthClient & {
+                botToken?: string;
+            };
+            google?: OAuthClient;
+        };
+        telegram?: {
+            botToken: string;
+            botUsername: string;
+        };
+        captcha?: {
+            turnstileSecret?: string;
+            hcaptchaSecret?: string;
+            recaptchaSecret?: string;
+        };
+        registry?: _solgate_core.ModuleRegistry;
+        verifiers?: Verifier[];
+    };
+};
+
+export { type AppEnv as A, EventBus as E, type NormalizedConfig as N, type ServerConfig as S, type Verifier as V, type Webhook as W, type Storage as a, type SocialLink as b, type WebhookDelivery as c, type ApiKey as d, type Snapshot as e, AllowlistError as f, AllowlistService as g, VerificationUnavailable as h, type VerifyContext as i, createAllowlistApp as j, fail as k, pass as p, verifyWebhookSignature as v };

package/dist/chunk-MCKGQKYU.js

@@ -0,0 +1,15 @@
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+
+export {
+  __require,
+  __commonJS
+};