@armory-sh/extensions 0.1.1

package/README.md

@@ -0,0 +1,101 @@
+# @armory-sh/extensions
+
+Protocol extensions for the x402 payment standard.
+
+## Installation
+
+```bash
+bun add @armory-sh/extensions
+```
+
+## Available Extensions
+
+| Extension | Purpose |
+|-----------|---------|
+| Sign-In-With-X | Wallet authentication for repeat access |
+| Payment Identifier | Idempotency for payment requests |
+| Bazaar | Resource discovery |
+
+## Hook Creators
+
+### createSIWxHook
+
+Creates a hook that handles Sign-In-With-X authentication:
+
+```typescript
+import { createSIWxHook } from '@armory-sh/extensions';
+import { createX402Client } from '@armory-sh/client-viem';
+
+const client = createX402Client({
+  wallet: { type: 'account', account },
+  hooks: {
+    siwx: createSIWxHook({
+      domain: 'example.com',
+      statement: 'Sign in to access premium content'
+    })
+  }
+});
+```
+
+### createPaymentIdHook
+
+Creates a hook that adds payment idempotency:
+
+```typescript
+import { createPaymentIdHook } from '@armory-sh/extensions';
+
+const hook = createPaymentIdHook({ paymentId: 'my-custom-id' });
+```
+
+### createCustomHook
+
+Create custom extension hooks:
+
+```typescript
+import { createCustomHook } from '@armory-sh/extensions';
+
+const customHook = createCustomHook({
+  key: 'my-extension',
+  handler: async (context) => {
+    if (context.payload) {
+      context.payload.extensions = {
+        ...(context.payload.extensions ?? {}),
+        'my-extension': { data: 'value' }
+      };
+    }
+  },
+  priority: 75
+});
+```
+
+## Server Extension Declaration
+
+For server-side middleware:
+
+```typescript
+import { declareSIWxExtension, declarePaymentIdentifierExtension } from '@armory-sh/extensions';
+
+const siwxExt = declareSIWxExtension({
+  domain: 'api.example.com',
+  statement: 'Sign in to access this API'
+});
+
+const paymentIdExt = declarePaymentIdentifierExtension({ required: true });
+```
+
+## Exports
+
+| Export | Description |
+|--------|-------------|
+| `createSIWxHook` | Hook for Sign-In-With-X |
+| `createPaymentIdHook` | Hook for payment idempotency |
+| `createCustomHook` | Create custom hooks |
+| `declareSIWxExtension` | Declare SIWX extension for server |
+| `declarePaymentIdentifierExtension` | Declare payment ID extension |
+| `validateSIWxMessage` | Validate SIWX payload |
+| `verifySIWxSignature` | Verify SIWX signature |
+| `generatePaymentId` | Generate random payment ID |
+
+## License
+
+MIT

package/dist/bazaar.js

@@ -0,0 +1,103 @@
+// src/validators.ts
+function extractExtension(extensions, key) {
+  if (!extensions || typeof extensions !== "object") {
+    return null;
+  }
+  const extension = extensions[key];
+  if (!extension || typeof extension !== "object") {
+    return null;
+  }
+  return extension;
+}
+function createExtension(info, schema) {
+  return { info, schema };
+}
+
+// src/types.ts
+var BAZAAR = "bazaar";
+
+// src/bazaar.ts
+var BAZAAR_SCHEMA = {
+  type: "object",
+  properties: {
+    input: {
+      description: "Expected input schema for the resource"
+    },
+    inputSchema: {
+      description: "JSON Schema for input validation",
+      type: "object"
+    },
+    output: {
+      type: "object",
+      properties: {
+        example: {
+          description: "Example output for the resource"
+        },
+        schema: {
+          description: "JSON Schema for output validation",
+          type: "object"
+        }
+      }
+    }
+  }
+};
+function declareDiscoveryExtension(config = {}) {
+  const info = {};
+  if (config.input !== void 0) {
+    info.input = config.input;
+  }
+  if (config.inputSchema !== void 0) {
+    info.inputSchema = config.inputSchema;
+  }
+  if (config.output !== void 0) {
+    info.output = config.output;
+  }
+  return createExtension(info, BAZAAR_SCHEMA);
+}
+function extractDiscoveryInfo(paymentPayload, paymentRequirements, validate = true) {
+  const extensions = paymentPayload.extensions;
+  const bazaarExtension = extractExtension(extensions, BAZAAR);
+  if (!bazaarExtension) {
+    return null;
+  }
+  return {
+    input: bazaarExtension.info.input,
+    inputSchema: bazaarExtension.info.inputSchema,
+    output: bazaarExtension.info.output,
+    network: paymentRequirements.network,
+    token: paymentRequirements.asset,
+    amount: paymentRequirements.amount,
+    payTo: paymentRequirements.payTo
+  };
+}
+function validateDiscoveryExtension(extension) {
+  if (!extension || typeof extension !== "object") {
+    return { valid: false, errors: ["Extension must be an object"] };
+  }
+  const ext = extension;
+  if (!("info" in ext) || typeof ext.info !== "object") {
+    return { valid: false, errors: ["Extension must have an 'info' field"] };
+  }
+  if (!("schema" in ext) || typeof ext.schema !== "object") {
+    return { valid: false, errors: ["Extension must have a 'schema' field"] };
+  }
+  return { valid: true };
+}
+function createDiscoveryConfig(config) {
+  return config;
+}
+function isDiscoveryExtension(extension) {
+  if (!extension || typeof extension !== "object") {
+    return false;
+  }
+  const ext = extension;
+  return "info" in ext && "schema" in ext;
+}
+export {
+  BAZAAR,
+  createDiscoveryConfig,
+  declareDiscoveryExtension,
+  extractDiscoveryInfo,
+  isDiscoveryExtension,
+  validateDiscoveryExtension
+};

package/dist/index.js

@@ -0,0 +1,557 @@
+// src/types.ts
+var BAZAAR = "bazaar";
+var SIGN_IN_WITH_X = "sign-in-with-x";
+var PAYMENT_IDENTIFIER = "payment-identifier";
+
+// src/validators.ts
+var ajvInstance = null;
+async function getAjv() {
+  if (!ajvInstance) {
+    const ajvModule = await import("ajv");
+    ajvInstance = new ajvModule.default({
+      allErrors: true,
+      strict: false
+    });
+  }
+  return ajvInstance;
+}
+async function validateExtension(extension, data) {
+  const ajv = await getAjv();
+  const validate = ajv.compile(extension.schema);
+  if (validate(data)) {
+    return { valid: true };
+  }
+  const errors = validate.errors?.map((err) => {
+    let path = "";
+    if (err.instancePath) {
+      path = err.instancePath;
+    } else if (err.schemaPath && Array.isArray(err.schemaPath)) {
+      path = err.schemaPath.join(".");
+    }
+    return `${path}: ${err.message || "validation error"}`;
+  });
+  return { valid: false, errors };
+}
+function extractExtension(extensions, key) {
+  if (!extensions || typeof extensions !== "object") {
+    return null;
+  }
+  const extension = extensions[key];
+  if (!extension || typeof extension !== "object") {
+    return null;
+  }
+  return extension;
+}
+function createExtension(info, schema) {
+  return { info, schema };
+}
+async function validateWithSchema(schema, data) {
+  const ajv = await getAjv();
+  const validate = ajv.compile(schema);
+  if (validate(data)) {
+    return { valid: true };
+  }
+  return {
+    valid: false,
+    errors: validate.errors || []
+  };
+}
+
+// src/bazaar.ts
+var BAZAAR_SCHEMA = {
+  type: "object",
+  properties: {
+    input: {
+      description: "Expected input schema for the resource"
+    },
+    inputSchema: {
+      description: "JSON Schema for input validation",
+      type: "object"
+    },
+    output: {
+      type: "object",
+      properties: {
+        example: {
+          description: "Example output for the resource"
+        },
+        schema: {
+          description: "JSON Schema for output validation",
+          type: "object"
+        }
+      }
+    }
+  }
+};
+function declareDiscoveryExtension(config = {}) {
+  const info = {};
+  if (config.input !== void 0) {
+    info.input = config.input;
+  }
+  if (config.inputSchema !== void 0) {
+    info.inputSchema = config.inputSchema;
+  }
+  if (config.output !== void 0) {
+    info.output = config.output;
+  }
+  return createExtension(info, BAZAAR_SCHEMA);
+}
+function extractDiscoveryInfo(paymentPayload, paymentRequirements, validate = true) {
+  const extensions = paymentPayload.extensions;
+  const bazaarExtension = extractExtension(extensions, BAZAAR);
+  if (!bazaarExtension) {
+    return null;
+  }
+  return {
+    input: bazaarExtension.info.input,
+    inputSchema: bazaarExtension.info.inputSchema,
+    output: bazaarExtension.info.output,
+    network: paymentRequirements.network,
+    token: paymentRequirements.asset,
+    amount: paymentRequirements.amount,
+    payTo: paymentRequirements.payTo
+  };
+}
+function validateDiscoveryExtension(extension) {
+  if (!extension || typeof extension !== "object") {
+    return { valid: false, errors: ["Extension must be an object"] };
+  }
+  const ext = extension;
+  if (!("info" in ext) || typeof ext.info !== "object") {
+    return { valid: false, errors: ["Extension must have an 'info' field"] };
+  }
+  if (!("schema" in ext) || typeof ext.schema !== "object") {
+    return { valid: false, errors: ["Extension must have a 'schema' field"] };
+  }
+  return { valid: true };
+}
+function createDiscoveryConfig(config) {
+  return config;
+}
+function isDiscoveryExtension(extension) {
+  if (!extension || typeof extension !== "object") {
+    return false;
+  }
+  const ext = extension;
+  return "info" in ext && "schema" in ext;
+}
+
+// src/sign-in-with-x.ts
+import { isAddress } from "@armory-sh/base";
+var SIWX_SCHEMA = {
+  type: "object",
+  properties: {
+    domain: {
+      type: "string",
+      description: "Domain requesting the sign-in"
+    },
+    resourceUri: {
+      type: "string",
+      description: "URI of the resource being accessed"
+    },
+    network: {
+      oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+      description: "Blockchain network(s) for authentication"
+    },
+    statement: {
+      type: "string",
+      description: "Human-readable statement about the sign-in"
+    },
+    version: {
+      type: "string",
+      description: "SIWX message version"
+    },
+    expirationSeconds: {
+      type: "number",
+      description: "Seconds until the message expires"
+    },
+    supportedChains: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          chainId: { type: "string" },
+          type: { type: "string" }
+        },
+        required: ["chainId", "type"]
+      }
+    }
+  }
+};
+var SIWX_HEADER_PATTERN = /^siwx-v1-(.+)$/;
+function base64UrlEncode(str) {
+  return btoa(str).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+function base64UrlDecode(str) {
+  let padded = str;
+  while (padded.length % 4) {
+    padded += "=";
+  }
+  return atob(padded.replace(/-/g, "+").replace(/_/g, "/"));
+}
+function declareSIWxExtension(config = {}) {
+  const info = {};
+  if (config.domain !== void 0) {
+    info.domain = config.domain;
+  }
+  if (config.resourceUri !== void 0) {
+    info.resourceUri = config.resourceUri;
+  }
+  if (config.network !== void 0) {
+    info.network = config.network;
+  }
+  if (config.statement !== void 0) {
+    info.statement = config.statement;
+  }
+  if (config.version !== void 0) {
+    info.version = config.version;
+  }
+  if (config.expirationSeconds !== void 0) {
+    info.expirationSeconds = config.expirationSeconds;
+  }
+  return createExtension(info, SIWX_SCHEMA);
+}
+function parseSIWxHeader(header) {
+  const match = header.match(SIWX_HEADER_PATTERN);
+  if (!match) {
+    throw new Error("Invalid SIWX header format");
+  }
+  try {
+    const decoded = base64UrlDecode(match[1]);
+    return JSON.parse(decoded);
+  } catch {
+    throw new Error("Failed to decode SIWX header");
+  }
+}
+function validateSIWxMessage(payload, resourceUri, options = {}) {
+  if (!payload.domain) {
+    return { valid: false, error: "Missing domain" };
+  }
+  if (!payload.address || !isAddress(payload.address)) {
+    return { valid: false, error: "Invalid or missing address" };
+  }
+  if (payload.resourceUri && payload.resourceUri !== resourceUri) {
+    return { valid: false, error: "Resource URI mismatch" };
+  }
+  if (payload.expirationTime) {
+    const expiration = new Date(payload.expirationTime).getTime();
+    const now = Date.now();
+    if (expiration < now) {
+      return { valid: false, error: "Message has expired" };
+    }
+  }
+  if (options.maxAge && payload.issuedAt) {
+    const issued = new Date(payload.issuedAt).getTime();
+    const now = Date.now();
+    const age = now - issued;
+    if (age > options.maxAge * 1e3) {
+      return { valid: false, error: "Message is too old" };
+    }
+  }
+  if (options.checkNonce && payload.nonce) {
+    if (!options.checkNonce(payload.nonce)) {
+      return { valid: false, error: "Invalid nonce" };
+    }
+  }
+  return { valid: true };
+}
+async function verifySIWxSignature(payload, options = {}) {
+  if (!payload.signature) {
+    return { valid: false, error: "Missing signature" };
+  }
+  if (!payload.address || !isAddress(payload.address)) {
+    return { valid: false, error: "Invalid address" };
+  }
+  if (options.evmVerifier) {
+    const message = createSIWxMessage(payload);
+    const valid = await options.evmVerifier(message, payload.signature, payload.address);
+    if (!valid) {
+      return { valid: false, error: "Signature verification failed" };
+    }
+  }
+  return { valid: true, address: payload.address };
+}
+function createSIWxMessage(payload) {
+  const lines = [];
+  lines.push(`${payload.domain} wants you to sign in`);
+  if (payload.statement) {
+    lines.push("");
+    lines.push(payload.statement);
+  }
+  lines.push("");
+  if (payload.resourceUri) {
+    lines.push(`URI: ${payload.resourceUri}`);
+  }
+  if (payload.version) {
+    lines.push(`Version: ${payload.version}`);
+  }
+  if (payload.nonce) {
+    lines.push(`Nonce: ${payload.nonce}`);
+  }
+  if (payload.issuedAt) {
+    lines.push(`Issued At: ${payload.issuedAt}`);
+  }
+  if (payload.expirationTime) {
+    lines.push(`Expiration Time: ${payload.expirationTime}`);
+  }
+  if (payload.chainId) {
+    const chains = Array.isArray(payload.chainId) ? payload.chainId.join(", ") : payload.chainId;
+    lines.push(`Chain ID(s): ${chains}`);
+  }
+  lines.push("");
+  lines.push(`Address: ${payload.address}`);
+  return lines.join("\n");
+}
+function encodeSIWxHeader(payload) {
+  const payloadStr = JSON.stringify(payload);
+  const encoded = base64UrlEncode(payloadStr);
+  return `siwx-v1-${encoded}`;
+}
+function createSIWxPayload(serverInfo, address, options = {}) {
+  const getDefaultDomain = () => {
+    if (typeof window !== "undefined" && window.location) {
+      return window.location.hostname;
+    }
+    return "localhost";
+  };
+  const payload = {
+    domain: serverInfo.domain || getDefaultDomain(),
+    address
+  };
+  if (serverInfo.resourceUri) {
+    payload.resourceUri = serverInfo.resourceUri;
+  }
+  if (serverInfo.statement) {
+    payload.statement = serverInfo.statement;
+  }
+  if (serverInfo.version) {
+    payload.version = serverInfo.version;
+  }
+  if (serverInfo.network) {
+    payload.chainId = serverInfo.network;
+  }
+  if (options.nonce) {
+    payload.nonce = options.nonce;
+  }
+  if (options.issuedAt) {
+    payload.issuedAt = options.issuedAt;
+  }
+  if (options.expirationTime) {
+    payload.expirationTime = options.expirationTime;
+  } else if (serverInfo.expirationSeconds) {
+    const expiration = new Date(Date.now() + serverInfo.expirationSeconds * 1e3);
+    payload.expirationTime = expiration.toISOString();
+  }
+  return payload;
+}
+function isSIWxExtension(extension) {
+  if (!extension || typeof extension !== "object") {
+    return false;
+  }
+  const ext = extension;
+  return "info" in ext && "schema" in ext;
+}
+
+// src/payment-identifier.ts
+var PAYMENT_ID_ALLOWED_CHARS = /^[a-z0-9_-]+$/;
+var PAYMENT_ID_MIN_LENGTH = 3;
+var PAYMENT_ID_MAX_LENGTH = 128;
+function generatePaymentId() {
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789-_";
+  let result = "";
+  for (let i = 0; i < 32; i++) {
+    const randomIndex = Math.floor(Math.random() * chars.length);
+    result += chars[randomIndex];
+  }
+  return result;
+}
+function appendPaymentIdentifierToExtensions(extensions, paymentId) {
+  const existing = extensions || {};
+  const extension = {
+    paymentId
+  };
+  return {
+    ...existing,
+    "payment-identifier": extension
+  };
+}
+function extractPaymentIdentifierInfo(paymentPayload) {
+  const extensions = paymentPayload.extensions;
+  if (!extensions || typeof extensions !== "object") {
+    return null;
+  }
+  const identifierExt = extensions["payment-identifier"];
+  if (!identifierExt || typeof identifierExt !== "object") {
+    return null;
+  }
+  const ext = identifierExt;
+  return ext.info?.paymentId || null;
+}
+function validatePaymentIdentifierExtension(extension) {
+  if (!extension || typeof extension !== "object") {
+    return { valid: false, errors: ["Extension must be an object"] };
+  }
+  const ext = extension;
+  if (!("info" in ext) || typeof ext.info !== "object") {
+    return { valid: false, errors: ["Extension must have an 'info' field"] };
+  }
+  const info = ext.info;
+  if (info.paymentId !== void 0) {
+    if (typeof info.paymentId !== "string") {
+      return { valid: false, errors: ["paymentId must be a string when defined"] };
+    }
+    if (info.paymentId.length > PAYMENT_ID_MAX_LENGTH) {
+      return { valid: false, errors: ["must be 128 characters or fewer"] };
+    }
+    if (info.paymentId.length < PAYMENT_ID_MIN_LENGTH) {
+      return {
+        valid: false,
+        errors: [`must be at least ${PAYMENT_ID_MIN_LENGTH} characters`]
+      };
+    }
+    if (!PAYMENT_ID_ALLOWED_CHARS.test(info.paymentId)) {
+      return {
+        valid: false,
+        errors: ["alphanumeric, hyphens, and underscores only"]
+      };
+    }
+  }
+  if (info.required !== void 0 && typeof info.required !== "boolean") {
+    return { valid: false, errors: ["required must be a boolean"] };
+  }
+  return { valid: true };
+}
+function isPaymentIdentifierExtension(extension) {
+  if (!extension || typeof extension !== "object") {
+    return false;
+  }
+  const ext = extension;
+  return "info" in ext && "schema" in ext;
+}
+function declarePaymentIdentifierExtension(config = {}) {
+  const info = {};
+  if (config.paymentId !== void 0) {
+    info.paymentId = config.paymentId;
+  }
+  if (config.required !== void 0) {
+    info.required = config.required;
+  }
+  const paymentIdSchema = {
+    type: "string",
+    minLength: PAYMENT_ID_MIN_LENGTH,
+    maxLength: PAYMENT_ID_MAX_LENGTH,
+    pattern: PAYMENT_ID_ALLOWED_CHARS.source,
+    description: "Unique payment identifier for idempotency"
+  };
+  if (info.required !== void 0) {
+    paymentIdSchema.required = [info.required];
+  }
+  return createExtension(info, {
+    type: "object",
+    properties: {
+      paymentId: paymentIdSchema,
+      required: {
+        type: "boolean",
+        description: "Whether payment identifier is required for this payment"
+      }
+    },
+    required: info.required ? ["paymentId"] : []
+  });
+}
+
+// src/hooks.ts
+function createSIWxHook(config) {
+  return {
+    hook: async (context) => {
+      if (!context.payload) return;
+      const serverExtensions = context.paymentContext?.serverExtensions;
+      const siwxInfo = serverExtensions?.["sign-in-with-x"];
+      if (!siwxInfo?.info) return;
+      const info = siwxInfo.info;
+      const address = context.paymentContext?.fromAddress;
+      const nonce = context.paymentContext?.nonce;
+      if (!address || !nonce) return;
+      const payload = createSIWxPayload(info, address, {
+        nonce: nonce.slice(2),
+        issuedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      const message = createSIWxMessage(payload);
+      const wallet = context.wallet;
+      let signature;
+      if (wallet.type === "account") {
+        signature = await wallet.account.signMessage({ message });
+      } else if (wallet.type === "walletClient") {
+        signature = await wallet.walletClient.account.signMessage({ message });
+      } else {
+        return;
+      }
+      payload.signature = signature;
+      const header = encodeSIWxHeader(payload);
+      context.payload.extensions = {
+        ...context.payload.extensions ?? {},
+        "sign-in-with-x": header
+      };
+    },
+    priority: 100,
+    name: "sign-in-with-x"
+  };
+}
+function createPaymentIdHook(config) {
+  const state = { paymentId: config?.paymentId };
+  return {
+    hook: async (context) => {
+      if (context.serverExtensions) {
+        const paymentIdExt = context.serverExtensions["payment-identifier"];
+        if (paymentIdExt && typeof paymentIdExt === "object") {
+          const info = paymentIdExt.info;
+          if (info?.required && !state.paymentId) {
+            state.paymentId = generatePaymentId();
+          }
+        }
+      }
+      if (context.payload && state.paymentId) {
+        context.payload.extensions = appendPaymentIdentifierToExtensions(
+          context.payload.extensions,
+          state.paymentId
+        );
+      }
+    },
+    priority: 50,
+    name: "payment-identifier"
+  };
+}
+function createCustomHook(config) {
+  return {
+    hook: config.handler,
+    priority: config.priority ?? 0,
+    name: config.key
+  };
+}
+export {
+  BAZAAR,
+  PAYMENT_IDENTIFIER,
+  SIGN_IN_WITH_X,
+  createCustomHook,
+  createDiscoveryConfig,
+  createExtension,
+  createPaymentIdHook,
+  createSIWxHook,
+  createSIWxMessage,
+  createSIWxPayload,
+  declareDiscoveryExtension,
+  declarePaymentIdentifierExtension,
+  declareSIWxExtension,
+  encodeSIWxHeader,
+  extractDiscoveryInfo,
+  extractExtension,
+  extractPaymentIdentifierInfo,
+  isDiscoveryExtension,
+  isPaymentIdentifierExtension,
+  isSIWxExtension,
+  parseSIWxHeader,
+  validateDiscoveryExtension,
+  validateExtension,
+  validatePaymentIdentifierExtension,
+  validateSIWxMessage,
+  validateWithSchema,
+  verifySIWxSignature
+};

package/dist/payment-identifier.js

@@ -0,0 +1,134 @@
+// src/validators.ts
+function createExtension(info, schema) {
+  return { info, schema };
+}
+
+// src/payment-identifier.ts
+var PAYMENT_ID_ALLOWED_CHARS = /^[a-z0-9_-]+$/;
+var PAYMENT_ID_MIN_LENGTH = 3;
+var PAYMENT_ID_MAX_LENGTH = 128;
+function generatePaymentId() {
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789-_";
+  let result = "";
+  for (let i = 0; i < 32; i++) {
+    const randomIndex = Math.floor(Math.random() * chars.length);
+    result += chars[randomIndex];
+  }
+  return result;
+}
+function appendPaymentIdentifierToExtensions(extensions, paymentId) {
+  const existing = extensions || {};
+  const extension = {
+    paymentId
+  };
+  return {
+    ...existing,
+    "payment-identifier": extension
+  };
+}
+function extractPaymentIdentifierInfo(paymentPayload) {
+  const extensions = paymentPayload.extensions;
+  if (!extensions || typeof extensions !== "object") {
+    return null;
+  }
+  const identifierExt = extensions["payment-identifier"];
+  if (!identifierExt || typeof identifierExt !== "object") {
+    return null;
+  }
+  const ext = identifierExt;
+  return ext.info?.paymentId || null;
+}
+function isValidPaymentId(paymentId) {
+  if (typeof paymentId !== "string") {
+    return false;
+  }
+  if (paymentId.length < PAYMENT_ID_MIN_LENGTH) {
+    return false;
+  }
+  if (paymentId.length > PAYMENT_ID_MAX_LENGTH) {
+    return false;
+  }
+  return PAYMENT_ID_ALLOWED_CHARS.test(paymentId);
+}
+function validatePaymentIdentifierExtension(extension) {
+  if (!extension || typeof extension !== "object") {
+    return { valid: false, errors: ["Extension must be an object"] };
+  }
+  const ext = extension;
+  if (!("info" in ext) || typeof ext.info !== "object") {
+    return { valid: false, errors: ["Extension must have an 'info' field"] };
+  }
+  const info = ext.info;
+  if (info.paymentId !== void 0) {
+    if (typeof info.paymentId !== "string") {
+      return { valid: false, errors: ["paymentId must be a string when defined"] };
+    }
+    if (info.paymentId.length > PAYMENT_ID_MAX_LENGTH) {
+      return { valid: false, errors: ["must be 128 characters or fewer"] };
+    }
+    if (info.paymentId.length < PAYMENT_ID_MIN_LENGTH) {
+      return {
+        valid: false,
+        errors: [`must be at least ${PAYMENT_ID_MIN_LENGTH} characters`]
+      };
+    }
+    if (!PAYMENT_ID_ALLOWED_CHARS.test(info.paymentId)) {
+      return {
+        valid: false,
+        errors: ["alphanumeric, hyphens, and underscores only"]
+      };
+    }
+  }
+  if (info.required !== void 0 && typeof info.required !== "boolean") {
+    return { valid: false, errors: ["required must be a boolean"] };
+  }
+  return { valid: true };
+}
+function isPaymentIdentifierExtension(extension) {
+  if (!extension || typeof extension !== "object") {
+    return false;
+  }
+  const ext = extension;
+  return "info" in ext && "schema" in ext;
+}
+function declarePaymentIdentifierExtension(config = {}) {
+  const info = {};
+  if (config.paymentId !== void 0) {
+    info.paymentId = config.paymentId;
+  }
+  if (config.required !== void 0) {
+    info.required = config.required;
+  }
+  const paymentIdSchema = {
+    type: "string",
+    minLength: PAYMENT_ID_MIN_LENGTH,
+    maxLength: PAYMENT_ID_MAX_LENGTH,
+    pattern: PAYMENT_ID_ALLOWED_CHARS.source,
+    description: "Unique payment identifier for idempotency"
+  };
+  if (info.required !== void 0) {
+    paymentIdSchema.required = [info.required];
+  }
+  return createExtension(info, {
+    type: "object",
+    properties: {
+      paymentId: paymentIdSchema,
+      required: {
+        type: "boolean",
+        description: "Whether payment identifier is required for this payment"
+      }
+    },
+    required: info.required ? ["paymentId"] : []
+  });
+}
+var PAYMENT_IDENTIFIER = "payment-identifier";
+export {
+  PAYMENT_IDENTIFIER,
+  appendPaymentIdentifierToExtensions,
+  declarePaymentIdentifierExtension,
+  extractPaymentIdentifierInfo,
+  generatePaymentId,
+  isPaymentIdentifierExtension,
+  isValidPaymentId,
+  validatePaymentIdentifierExtension
+};

package/dist/sign-in-with-x.js

@@ -0,0 +1,236 @@
+// src/validators.ts
+function createExtension(info, schema) {
+  return { info, schema };
+}
+
+// src/sign-in-with-x.ts
+import { isAddress } from "@armory-sh/base";
+
+// src/types.ts
+var SIGN_IN_WITH_X = "sign-in-with-x";
+
+// src/sign-in-with-x.ts
+var SIWX_SCHEMA = {
+  type: "object",
+  properties: {
+    domain: {
+      type: "string",
+      description: "Domain requesting the sign-in"
+    },
+    resourceUri: {
+      type: "string",
+      description: "URI of the resource being accessed"
+    },
+    network: {
+      oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+      description: "Blockchain network(s) for authentication"
+    },
+    statement: {
+      type: "string",
+      description: "Human-readable statement about the sign-in"
+    },
+    version: {
+      type: "string",
+      description: "SIWX message version"
+    },
+    expirationSeconds: {
+      type: "number",
+      description: "Seconds until the message expires"
+    },
+    supportedChains: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          chainId: { type: "string" },
+          type: { type: "string" }
+        },
+        required: ["chainId", "type"]
+      }
+    }
+  }
+};
+var SIWX_HEADER_PATTERN = /^siwx-v1-(.+)$/;
+function base64UrlEncode(str) {
+  return btoa(str).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+function base64UrlDecode(str) {
+  let padded = str;
+  while (padded.length % 4) {
+    padded += "=";
+  }
+  return atob(padded.replace(/-/g, "+").replace(/_/g, "/"));
+}
+function declareSIWxExtension(config = {}) {
+  const info = {};
+  if (config.domain !== void 0) {
+    info.domain = config.domain;
+  }
+  if (config.resourceUri !== void 0) {
+    info.resourceUri = config.resourceUri;
+  }
+  if (config.network !== void 0) {
+    info.network = config.network;
+  }
+  if (config.statement !== void 0) {
+    info.statement = config.statement;
+  }
+  if (config.version !== void 0) {
+    info.version = config.version;
+  }
+  if (config.expirationSeconds !== void 0) {
+    info.expirationSeconds = config.expirationSeconds;
+  }
+  return createExtension(info, SIWX_SCHEMA);
+}
+function parseSIWxHeader(header) {
+  const match = header.match(SIWX_HEADER_PATTERN);
+  if (!match) {
+    throw new Error("Invalid SIWX header format");
+  }
+  try {
+    const decoded = base64UrlDecode(match[1]);
+    return JSON.parse(decoded);
+  } catch {
+    throw new Error("Failed to decode SIWX header");
+  }
+}
+function validateSIWxMessage(payload, resourceUri, options = {}) {
+  if (!payload.domain) {
+    return { valid: false, error: "Missing domain" };
+  }
+  if (!payload.address || !isAddress(payload.address)) {
+    return { valid: false, error: "Invalid or missing address" };
+  }
+  if (payload.resourceUri && payload.resourceUri !== resourceUri) {
+    return { valid: false, error: "Resource URI mismatch" };
+  }
+  if (payload.expirationTime) {
+    const expiration = new Date(payload.expirationTime).getTime();
+    const now = Date.now();
+    if (expiration < now) {
+      return { valid: false, error: "Message has expired" };
+    }
+  }
+  if (options.maxAge && payload.issuedAt) {
+    const issued = new Date(payload.issuedAt).getTime();
+    const now = Date.now();
+    const age = now - issued;
+    if (age > options.maxAge * 1e3) {
+      return { valid: false, error: "Message is too old" };
+    }
+  }
+  if (options.checkNonce && payload.nonce) {
+    if (!options.checkNonce(payload.nonce)) {
+      return { valid: false, error: "Invalid nonce" };
+    }
+  }
+  return { valid: true };
+}
+async function verifySIWxSignature(payload, options = {}) {
+  if (!payload.signature) {
+    return { valid: false, error: "Missing signature" };
+  }
+  if (!payload.address || !isAddress(payload.address)) {
+    return { valid: false, error: "Invalid address" };
+  }
+  if (options.evmVerifier) {
+    const message = createSIWxMessage(payload);
+    const valid = await options.evmVerifier(message, payload.signature, payload.address);
+    if (!valid) {
+      return { valid: false, error: "Signature verification failed" };
+    }
+  }
+  return { valid: true, address: payload.address };
+}
+function createSIWxMessage(payload) {
+  const lines = [];
+  lines.push(`${payload.domain} wants you to sign in`);
+  if (payload.statement) {
+    lines.push("");
+    lines.push(payload.statement);
+  }
+  lines.push("");
+  if (payload.resourceUri) {
+    lines.push(`URI: ${payload.resourceUri}`);
+  }
+  if (payload.version) {
+    lines.push(`Version: ${payload.version}`);
+  }
+  if (payload.nonce) {
+    lines.push(`Nonce: ${payload.nonce}`);
+  }
+  if (payload.issuedAt) {
+    lines.push(`Issued At: ${payload.issuedAt}`);
+  }
+  if (payload.expirationTime) {
+    lines.push(`Expiration Time: ${payload.expirationTime}`);
+  }
+  if (payload.chainId) {
+    const chains = Array.isArray(payload.chainId) ? payload.chainId.join(", ") : payload.chainId;
+    lines.push(`Chain ID(s): ${chains}`);
+  }
+  lines.push("");
+  lines.push(`Address: ${payload.address}`);
+  return lines.join("\n");
+}
+function encodeSIWxHeader(payload) {
+  const payloadStr = JSON.stringify(payload);
+  const encoded = base64UrlEncode(payloadStr);
+  return `siwx-v1-${encoded}`;
+}
+function createSIWxPayload(serverInfo, address, options = {}) {
+  const getDefaultDomain = () => {
+    if (typeof window !== "undefined" && window.location) {
+      return window.location.hostname;
+    }
+    return "localhost";
+  };
+  const payload = {
+    domain: serverInfo.domain || getDefaultDomain(),
+    address
+  };
+  if (serverInfo.resourceUri) {
+    payload.resourceUri = serverInfo.resourceUri;
+  }
+  if (serverInfo.statement) {
+    payload.statement = serverInfo.statement;
+  }
+  if (serverInfo.version) {
+    payload.version = serverInfo.version;
+  }
+  if (serverInfo.network) {
+    payload.chainId = serverInfo.network;
+  }
+  if (options.nonce) {
+    payload.nonce = options.nonce;
+  }
+  if (options.issuedAt) {
+    payload.issuedAt = options.issuedAt;
+  }
+  if (options.expirationTime) {
+    payload.expirationTime = options.expirationTime;
+  } else if (serverInfo.expirationSeconds) {
+    const expiration = new Date(Date.now() + serverInfo.expirationSeconds * 1e3);
+    payload.expirationTime = expiration.toISOString();
+  }
+  return payload;
+}
+function isSIWxExtension(extension) {
+  if (!extension || typeof extension !== "object") {
+    return false;
+  }
+  const ext = extension;
+  return "info" in ext && "schema" in ext;
+}
+export {
+  SIGN_IN_WITH_X,
+  createSIWxMessage,
+  createSIWxPayload,
+  declareSIWxExtension,
+  encodeSIWxHeader,
+  isSIWxExtension,
+  parseSIWxHeader,
+  validateSIWxMessage,
+  verifySIWxSignature
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@armory-sh/extensions",
+  "version": "0.1.1",
+  "license": "MIT",
+  "author": "Sawyer Cutler <sawyer@dirtroad.dev>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./bazaar": {
+      "types": "./dist/bazaar.d.ts",
+      "bun": "./src/bazaar.ts",
+      "default": "./dist/bazaar.js"
+    },
+    "./sign-in-with-x": {
+      "types": "./dist/sign-in-with-x.d.ts",
+      "bun": "./src/sign-in-with-x.ts",
+      "default": "./dist/sign-in-with-x.js"
+    },
+    "./payment-identifier": {
+      "types": "./dist/payment-identifier.d.ts",
+      "bun": "./src/payment-identifier.ts",
+      "default": "./dist/payment-identifier.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thegreataxios/armory.git",
+    "directory": "packages/extensions"
+  },
+  "dependencies": {
+    "@armory-sh/base": "0.2.20",
+    "ajv": "^8.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.1",
+    "bun-types": "latest",
+    "tsup": "^8.0.0",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsup",
+    "build:dts": "rm -rf dist && tsc --declaration --skipLibCheck",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  }
+}