@bolyra/receipts 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -4,3 +4,4 @@ export { signReceipt, verifyReceipt, hashPayload } from './sign';
 export { GENESIS_PREV_RECEIPT_HASH, ReceiptChain, computeReceiptHash, verifyReceiptChain, } from './chain';
 export type { ReceiptChainIssue, ReceiptChainIssueCode, ChainVerifyOptions, ChainVerifyResult, } from './chain';
 export type { ReceiptPayload, ReceiptChainFields, SignedReceipt, ReceiptSignerConfig, AuthReceiptInput, CommerceReceiptInput, CommerceFields, } from './types';
+export { parseSignerDiscovery, acceptedSigners, SignerDiscoveryError, type SignerDiscoveryDocument, type DiscoveredSigner, } from './signer-discovery';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.verifyReceiptChain = exports.computeReceiptHash = exports.ReceiptChain = exports.GENESIS_PREV_RECEIPT_HASH = exports.hashPayload = exports.verifyReceipt = exports.signReceipt = exports.createCommerceReceipt = exports.createAuthReceipt = exports.canonicalize = void 0;
+exports.SignerDiscoveryError = exports.acceptedSigners = exports.parseSignerDiscovery = exports.verifyReceiptChain = exports.computeReceiptHash = exports.ReceiptChain = exports.GENESIS_PREV_RECEIPT_HASH = exports.hashPayload = exports.verifyReceipt = exports.signReceipt = exports.createCommerceReceipt = exports.createAuthReceipt = exports.canonicalize = void 0;
 var canonical_1 = require("./canonical");
 Object.defineProperty(exports, "canonicalize", { enumerable: true, get: function () { return canonical_1.canonicalize; } });
 var receipt_1 = require("./receipt");
@@ -15,3 +15,7 @@ Object.defineProperty(exports, "GENESIS_PREV_RECEIPT_HASH", { enumerable: true,
 Object.defineProperty(exports, "ReceiptChain", { enumerable: true, get: function () { return chain_1.ReceiptChain; } });
 Object.defineProperty(exports, "computeReceiptHash", { enumerable: true, get: function () { return chain_1.computeReceiptHash; } });
 Object.defineProperty(exports, "verifyReceiptChain", { enumerable: true, get: function () { return chain_1.verifyReceiptChain; } });
+var signer_discovery_1 = require("./signer-discovery");
+Object.defineProperty(exports, "parseSignerDiscovery", { enumerable: true, get: function () { return signer_discovery_1.parseSignerDiscovery; } });
+Object.defineProperty(exports, "acceptedSigners", { enumerable: true, get: function () { return signer_discovery_1.acceptedSigners; } });
+Object.defineProperty(exports, "SignerDiscoveryError", { enumerable: true, get: function () { return signer_discovery_1.SignerDiscoveryError; } });

package/dist/signer-discovery.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Receipt Signer Discovery v1 — canonical parser/validator.
+ * Spec: spec/receipt-signer-discovery-v1.md. Discovery is not endorsement:
+ * this module validates document SHAPE; deciding to trust the origin that
+ * served it stays with the consumer.
+ */
+export declare class SignerDiscoveryError extends Error {
+    constructor(message: string);
+}
+export interface DiscoveredSigner {
+    keyId: string;
+    alg: 'ES256K';
+    signer: string;
+    label?: string;
+}
+export interface SignerDiscoveryDocument {
+    v: 1;
+    issuer: string;
+    updatedAt: number;
+    signers: DiscoveredSigner[];
+}
+/**
+ * Validate an untrusted JSON value as a v1 signer discovery document.
+ * Throws SignerDiscoveryError on any spec violation (consumers MUST treat
+ * that as verification failure — fail closed). Unknown fields are ignored.
+ */
+export declare function parseSignerDiscovery(input: unknown): SignerDiscoveryDocument;
+/** Lowercased accepted signer addresses from a validated document. */
+export declare function acceptedSigners(doc: SignerDiscoveryDocument): Set<string>;

package/dist/signer-discovery.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Receipt Signer Discovery v1 — canonical parser/validator.
+ * Spec: spec/receipt-signer-discovery-v1.md. Discovery is not endorsement:
+ * this module validates document SHAPE; deciding to trust the origin that
+ * served it stays with the consumer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SignerDiscoveryError = void 0;
+exports.parseSignerDiscovery = parseSignerDiscovery;
+exports.acceptedSigners = acceptedSigners;
+const SIGNER_RE = /^0x[0-9a-fA-F]{40}$/;
+class SignerDiscoveryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SignerDiscoveryError';
+    }
+}
+exports.SignerDiscoveryError = SignerDiscoveryError;
+function bad(field, why) {
+    throw new SignerDiscoveryError(`signer discovery document invalid: ${field} ${why}`);
+}
+/**
+ * Validate an untrusted JSON value as a v1 signer discovery document.
+ * Throws SignerDiscoveryError on any spec violation (consumers MUST treat
+ * that as verification failure — fail closed). Unknown fields are ignored.
+ */
+function parseSignerDiscovery(input) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        bad('document', 'must be a JSON object');
+    }
+    const doc = input;
+    if (doc.v !== 1)
+        bad('v', 'must be the number 1');
+    if (typeof doc.issuer !== 'string' || doc.issuer.length === 0) {
+        bad('issuer', 'must be a non-empty string');
+    }
+    if (typeof doc.updatedAt !== 'number' || !Number.isFinite(doc.updatedAt)) {
+        bad('updatedAt', 'must be a number (unix seconds)');
+    }
+    if (!Array.isArray(doc.signers) || doc.signers.length === 0) {
+        bad('signers', 'must be a non-empty array');
+    }
+    const byKeyId = new Map();
+    const signers = doc.signers.map((raw, i) => {
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            bad(`signers[${i}]`, 'must be an object');
+        }
+        const e = raw;
+        if (typeof e.keyId !== 'string' || e.keyId.length === 0) {
+            bad(`signers[${i}].keyId`, 'must be a non-empty string');
+        }
+        if (e.alg !== 'ES256K') {
+            bad(`signers[${i}].alg`, 'must be "ES256K" in v1 (closed set)');
+        }
+        if (typeof e.signer !== 'string' || !SIGNER_RE.test(e.signer)) {
+            bad(`signers[${i}].signer`, 'must match ^0x[0-9a-fA-F]{40}$');
+        }
+        if (e.label !== undefined && typeof e.label !== 'string') {
+            bad(`signers[${i}].label`, 'must be a string when present');
+        }
+        const keyId = e.keyId;
+        const signer = e.signer.toLowerCase();
+        const seen = byKeyId.get(keyId);
+        if (seen !== undefined && seen !== signer) {
+            bad(`signers[${i}].keyId`, `"${keyId}" appears twice with conflicting signer values`);
+        }
+        byKeyId.set(keyId, signer);
+        return {
+            keyId,
+            alg: 'ES256K',
+            signer: e.signer,
+            ...(e.label !== undefined ? { label: e.label } : {}),
+        };
+    });
+    return { v: 1, issuer: doc.issuer, updatedAt: doc.updatedAt, signers };
+}
+/** Lowercased accepted signer addresses from a validated document. */
+function acceptedSigners(doc) {
+    return new Set(doc.signers.map((s) => s.signer.toLowerCase()));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bolyra/receipts",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Signed auth receipts for Bolyra ZKP verification decisions — canonical JSON, secp256k1 sign/verify, EVM-compatible r||s||v signatures.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -22,3 +22,10 @@ export type {
   CommerceReceiptInput,
   CommerceFields,
 } from './types';
+export {
+  parseSignerDiscovery,
+  acceptedSigners,
+  SignerDiscoveryError,
+  type SignerDiscoveryDocument,
+  type DiscoveredSigner,
+} from './signer-discovery';

package/src/signer-discovery.ts

@@ -0,0 +1,96 @@
+/**
+ * Receipt Signer Discovery v1 — canonical parser/validator.
+ * Spec: spec/receipt-signer-discovery-v1.md. Discovery is not endorsement:
+ * this module validates document SHAPE; deciding to trust the origin that
+ * served it stays with the consumer.
+ */
+
+const SIGNER_RE = /^0x[0-9a-fA-F]{40}$/;
+
+export class SignerDiscoveryError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SignerDiscoveryError';
+  }
+}
+
+export interface DiscoveredSigner {
+  keyId: string;
+  alg: 'ES256K';
+  signer: string;
+  label?: string;
+}
+
+export interface SignerDiscoveryDocument {
+  v: 1;
+  issuer: string;
+  updatedAt: number;
+  signers: DiscoveredSigner[];
+}
+
+function bad(field: string, why: string): never {
+  throw new SignerDiscoveryError(`signer discovery document invalid: ${field} ${why}`);
+}
+
+/**
+ * Validate an untrusted JSON value as a v1 signer discovery document.
+ * Throws SignerDiscoveryError on any spec violation (consumers MUST treat
+ * that as verification failure — fail closed). Unknown fields are ignored.
+ */
+export function parseSignerDiscovery(input: unknown): SignerDiscoveryDocument {
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+    bad('document', 'must be a JSON object');
+  }
+  const doc = input as Record<string, unknown>;
+
+  if (doc.v !== 1) bad('v', 'must be the number 1');
+  if (typeof doc.issuer !== 'string' || doc.issuer.length === 0) {
+    bad('issuer', 'must be a non-empty string');
+  }
+  if (typeof doc.updatedAt !== 'number' || !Number.isFinite(doc.updatedAt)) {
+    bad('updatedAt', 'must be a number (unix seconds)');
+  }
+  if (!Array.isArray(doc.signers) || doc.signers.length === 0) {
+    bad('signers', 'must be a non-empty array');
+  }
+
+  const byKeyId = new Map<string, string>();
+  const signers: DiscoveredSigner[] = doc.signers.map((raw, i) => {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+      bad(`signers[${i}]`, 'must be an object');
+    }
+    const e = raw as Record<string, unknown>;
+    if (typeof e.keyId !== 'string' || e.keyId.length === 0) {
+      bad(`signers[${i}].keyId`, 'must be a non-empty string');
+    }
+    if (e.alg !== 'ES256K') {
+      bad(`signers[${i}].alg`, 'must be "ES256K" in v1 (closed set)');
+    }
+    if (typeof e.signer !== 'string' || !SIGNER_RE.test(e.signer)) {
+      bad(`signers[${i}].signer`, 'must match ^0x[0-9a-fA-F]{40}$');
+    }
+    if (e.label !== undefined && typeof e.label !== 'string') {
+      bad(`signers[${i}].label`, 'must be a string when present');
+    }
+    const keyId = e.keyId as string;
+    const signer = (e.signer as string).toLowerCase();
+    const seen = byKeyId.get(keyId);
+    if (seen !== undefined && seen !== signer) {
+      bad(`signers[${i}].keyId`, `"${keyId}" appears twice with conflicting signer values`);
+    }
+    byKeyId.set(keyId, signer);
+    return {
+      keyId,
+      alg: 'ES256K' as const,
+      signer: e.signer as string,
+      ...(e.label !== undefined ? { label: e.label as string } : {}),
+    };
+  });
+
+  return { v: 1, issuer: doc.issuer as string, updatedAt: doc.updatedAt as number, signers };
+}
+
+/** Lowercased accepted signer addresses from a validated document. */
+export function acceptedSigners(doc: SignerDiscoveryDocument): Set<string> {
+  return new Set(doc.signers.map((s) => s.signer.toLowerCase()));
+}