chit402-verify 0.3.5 → 0.4.0

package/dist/issuer-pin.d.ts

@@ -0,0 +1,126 @@
+import { type Es256Jwk } from './jws.js';
+export declare const ISSUER_REGISTRATION_CONTEXT = "chit402-issuer-registration-v1";
+export declare const ISSUER_ROTATION_CONTEXT = "chit402-issuer-rotation-v1";
+export declare const ISSUER_PIN_VERSION = 1;
+export declare const ISSUER_PIN_SCHEMA = "chit402.issuer_key_pin.v1";
+export declare const ISSUER_PIN_PATH = "docs/well-known/issuer-key.json";
+export declare const ISSUER_PIN_CHAIN_ID = "eip155:84532";
+export declare const CITIZEN_FREEZE_SCHEMA = "chit402.freeze.v1";
+export declare const CITIZEN_FREEZE_PURPOSE = "citizen_issuer_key";
+export declare const ISSUER_PIN_REPO = "XFuel-Lab/chit402";
+/**
+ * Kid of the Sepolia specimen in docs/well-known/issuer-key.json.
+ * A different kid is a rotation and needs the previous pin.
+ */
+export declare const PUBLISHED_ISSUER_PIN_KID = "kATmVjz6J8QvSTS-bS1NUjWaLs35o-PXYurO2blMf-c";
+export declare const ISSUER_PIN_MISMATCH = "ISSUER_PIN_MISMATCH";
+export declare const ISSUER_PIN_HASH_MISMATCH = "ISSUER_PIN_HASH_MISMATCH";
+export declare const ISSUER_SELF_SIG_INVALID = "ISSUER_SELF_SIG_INVALID";
+export declare const ISSUER_PIN_DOWNGRADE = "ISSUER_PIN_DOWNGRADE";
+export declare const ISSUER_PIN_MUTABLE_REF = "ISSUER_PIN_MUTABLE_REF";
+export declare const ISSUER_ROTATION_UNCONTROLLED = "ISSUER_ROTATION_UNCONTROLLED";
+export declare const ISSUER_PIN_CHAIN_REFUSED = "ISSUER_PIN_CHAIN_REFUSED";
+export interface IssuerPinRef {
+    commit: string;
+    path: string;
+    sha256: string;
+}
+export interface IssuerPinAssessment {
+    checked: boolean;
+    ok: boolean;
+    code: string | null;
+}
+export interface IssuerKeyPin {
+    schema: typeof ISSUER_PIN_SCHEMA;
+    version: number;
+    chain_id: string;
+    created_at: string;
+    jwk: Es256Jwk;
+    self_signature: string | null;
+    control: {
+        jws: string;
+    } | null;
+}
+export declare function issuerPinFileHash(bytes: string): string;
+export declare function canonicalPublicKey(jwk: Pick<Es256Jwk, 'crv' | 'kty' | 'x' | 'y'>): string;
+/**
+ * Registration preimage. The context, version, kid, created_at, and key
+ * are fixed fields, so a signature over another purpose or another key
+ * does not verify.
+ */
+export declare function registrationPreimage(input: {
+    kid: string;
+    createdAt: string;
+    jwk: Es256Jwk;
+}): string;
+export declare function rotationStatement(input: {
+    priorKid: string;
+    nextKid: string;
+    pinSha256: string;
+    pinCommit: string;
+    createdAt: string;
+}): string;
+export declare function serializeIssuerPin(doc: IssuerKeyPin): string;
+/**
+ * URL of the pin blob at one commit. A branch, HEAD, or any non-40-hex
+ * ref returns ISSUER_PIN_MUTABLE_REF and does not build a URL.
+ */
+export declare function issuerPinContentUrl(commit: string, path?: string): {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    code: typeof ISSUER_PIN_MUTABLE_REF;
+};
+export declare function loadIssuerPinBytes(ref: IssuerPinRef, fetchImpl: (url: string) => Promise<Uint8Array>): Promise<{
+    ok: true;
+    bytes: string;
+} | {
+    ok: false;
+    code: string;
+}>;
+export declare function readIssuerPinClaim(doc: unknown): {
+    claimed: boolean;
+    ref: IssuerPinRef | null;
+};
+export declare function verifyRegistrationSignature(pin: IssuerKeyPin): {
+    ok: boolean;
+    code: string | null;
+};
+export declare function verifyCitizenRotation(input: {
+    prior: IssuerKeyPin;
+    next: IssuerKeyPin;
+    nextHash: string;
+    nextCommit: string;
+    controlJws: string | null;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    code: string;
+};
+export interface AssessIssuerPinInput {
+    receipt?: unknown;
+    head?: unknown;
+    pinBytes?: string | null;
+    sigBytes?: string | null;
+    ref?: IssuerPinRef | null;
+    witnesses?: unknown;
+    priorPinBytes?: string | null;
+    priorRef?: IssuerPinRef | null;
+    controlJws?: string | null;
+    required?: boolean;
+    /**
+     * Ignored. The specimen kid gate is not optional. A caller cannot
+     * turn it off by passing a prior pin or by setting this to false.
+     */
+    anchorToPublished?: boolean;
+}
+/**
+ * Compare a receipt's issuer key to the pinned file, and to issuer_root
+ * and a /api/witnesses document when those sources are present.
+ * A receipt or head that claims a pinned era and omits the pin fails closed.
+ * No claim and no explicit pin leaves the caller on the previous path.
+ */
+export declare function assessIssuerPin(input: AssessIssuerPinInput): IssuerPinAssessment;
+//# sourceMappingURL=issuer-pin.d.ts.map

package/dist/issuer-pin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issuer-pin.d.ts","sourceRoot":"","sources":["../src/issuer-pin.ts"],"names":[],"mappings":"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"}