@majikah/majik-signature 0.2.8 → 0.2.9

package/README.md

@@ -1,7 +1,7 @@
 # Majik Signature
 
 [![Developed by Zelijah](https://img.shields.io/badge/Developed%20by-Zelijah-red?logo=github&logoColor=white)](https://thezelijah.world) ![GitHub Sponsors](https://img.shields.io/github/sponsors/jedlsf?style=plastic&label=Sponsors&link=https%3A%2F%2Fgithub.com%2Fsponsors%2Fjedlsf)
-![npm](https://img.shields.io/npm/v/@majikah/majik-signature) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-signature) ![npm bundle size](https://img.shields.io/bundlephobia/min/%40majikah%2Fmajik-signature) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
+![npm](https://img.shields.io/npm/v/@majikah/majik-signature) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-signature) ![npm bundle size](https://img.shields.io/bundlephobia/min/%40majikah%2Fmajik-signature) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue) [![Static Badge](https://img.shields.io/badge/IANA-vnd.majikah.mjksig-green)](https://www.iana.org/assignments/media-types/application/vnd.majikah.mjksig)
 
 **Majik Signature** is a hybrid post-quantum content signing and verification library for the Majikah ecosystem. Built on top of [**Majik Key**](https://www.npmjs.com/package/@majikah/majik-key), it produces tamper-evident, forgery-resistant digital signatures for any content — plaintext, JSON, PDFs, audio, video, Office documents, or raw binary — using a dual-algorithm architecture that combines classical **Ed25519** with post-quantum **ML-DSA-87** (FIPS-204).
 
@@ -196,6 +196,8 @@ Verification is fully **public** — anyone with the signer's public keys can ve
 
 ### Detached Signing & Batch Workflows
 
+[![Static Badge](https://img.shields.io/badge/IANA-vnd.majikah.mjksig-green)](https://www.iana.org/assignments/media-types/application/vnd.majikah.mjksig)
+
 - **Detached envelopes** — sign a file and receive the envelope separately, for external verification pipelines where payload and signature travel independently
 - **Self-describing binary containers** — `.mjksig` for a single detached envelope, `.mjksmap` for a manifest covering an entire batch, each with magic bytes, a version header, and a length-prefixed payload
 - **Batch signing** — sign every file in a folder or zip in one call, packaged as one `.mjksmap` manifest or as separate `.mjksig` files per asset

package/dist/core/embed/majik-embed.d.ts

@@ -20,7 +20,7 @@
  * reduced to file-format orchestration: read bytes → resolve handler →
  * extract/strip → delegate to the envelope class → re-embed.
  */
-import type { MajikKey } from "@majikah/majik-key";
+import type { ISODateString, MajikKey } from "@majikah/majik-key";
 import type { BatchFileInput, BatchSignOptions, BatchSignResult, BatchVerifyInput, BatchVerifyOptions, BatchVerifySummary, EmbedOptions, EmbedResult, EnvelopeInfo, ExpectedSigner, ExtractOptions, ExtractResult, FileVerifyResult, MajikSignatureEnvelopeJSON, MajikSignatureJSON, MajikSignerPublicKeys, MajikTimestamp, SealInfo, SealVerificationResult, SignatoriesFilter, SignatoriesResult, SignOptions, VerificationResult } from "../../core/types";
 import { MajikSignatureEnvelope } from "../../core/envelope";
 import { FormatHandlerRegistry } from "./registry";
@@ -40,7 +40,7 @@ export interface MajikSignatureStaticAdapter {
     sign(content: Uint8Array | string, key: MajikKey, options?: SignOptions & {
         allowlistHash?: string;
     }): Promise<MajikSignatureAdapter>;
-    verify(content: Uint8Array | string, signature: MajikSignatureAdapter | MajikSignatureJSON, publicKeys: MajikSignerPublicKeys): VerificationResult;
+    verify(content: Uint8Array | string, signature: MajikSignatureAdapter | MajikSignatureJSON, publicKeys: MajikSignerPublicKeys, now?: Date): VerificationResult;
     publicKeysFromMajikKey(key: MajikKey): MajikSignerPublicKeys;
     fromJSON(json: MajikSignatureJSON | string): MajikSignatureAdapter;
 }
@@ -69,8 +69,10 @@ export declare class MajikSignatureEmbed {
      */
     static signAndEmbed<T extends MajikSignatureAdapter>(file: Blob, key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: EmbedOptions & {
         contentType?: string;
-        timestamp?: string;
+        timestamp?: ISODateString;
         expectedSigners?: ExpectedSigner[];
+        /** ISO 8601 expiry for this signature. Omit for one that never expires. */
+        validUntil?: ISODateString;
     }, debug?: boolean): Promise<EmbedResult & {
         signature: T;
         envelope: MajikSignatureEnvelope;
@@ -95,7 +97,9 @@ export declare class MajikSignatureEmbed {
      */
     static signDetached<T extends MajikSignatureAdapter = MajikSignatureAdapter>(file: Blob, key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: EmbedOptions & {
         contentType?: string;
-        timestamp?: string;
+        timestamp?: ISODateString;
+        /** ISO 8601 expiry for this signature. Omit for one that never expires. */
+        validUntil?: ISODateString;
         expectedSigners?: ExpectedSigner[];
         existingEnvelope?: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob;
         tsa?: MajikTimestamp;
@@ -140,9 +144,11 @@ export declare class MajikSignatureEmbed {
      */
     static verify(file: Blob, publicKeys: MajikSignerPublicKeys, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
         expectedSignerId?: string;
+        now?: Date;
     }, debug?: boolean): Promise<VerificationResult[]>;
     static verifyWithKey(file: Blob, key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
         expectedSignerId?: string;
+        now?: Date;
     }, debug?: boolean): Promise<VerificationResult[]>;
     /**
      * Verify a file against a provided, detached envelope (instance, blob or JSON).
@@ -151,9 +157,12 @@ export declare class MajikSignatureEmbed {
      */
     static verifyDetached(file: Blob, envelopeInput: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob, publicKeys: MajikSignerPublicKeys, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
         expectedSignerId?: string;
-    }, debug?: boolean): Promise<VerificationResult[]>;
+        now?: Date;
+    }, // FIX
+    debug?: boolean): Promise<VerificationResult[]>;
     static verifyDetachedWithKey(file: Blob, envelopeInput: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob, key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
         expectedSignerId?: string;
+        now?: Date;
     }, debug?: boolean): Promise<VerificationResult[]>;
     /**
      * Verify a batch of extracted files against a MajikSignatureMap.

package/dist/core/embed/majik-embed.js

@@ -37,7 +37,7 @@ import { FallbackHandler } from "./fallback";
 import { bytesToBase64, hashContent } from "../hash";
 import { MajikSignatureError, MajikSignatureValidationError } from "../errors";
 import { MajikSignatureMap } from "../mjksmap";
-import { verifySignatureOrder } from "../order";
+import { verifySignatureOrder, } from "../order";
 // ─── Registry ─────────────────────────────────────────────────────────────────
 const DEFAULT_REGISTRY = new FormatHandlerRegistry()
     .register(new PdfHandler())
@@ -104,6 +104,7 @@ export class MajikSignatureEmbed {
         const signature = await MajikSig.sign(originalBytes, key, {
             contentType: options?.contentType,
             timestamp: options?.timestamp,
+            validUntil: options?.validUntil,
             ...(allowlistHashValue !== undefined
                 ? { allowlistHash: allowlistHashValue }
                 : {}),
@@ -161,6 +162,7 @@ export class MajikSignatureEmbed {
         const signature = await MajikSig.sign(originalBytes, key, {
             contentType: options?.contentType,
             timestamp: options?.timestamp,
+            validUntil: options?.validUntil,
             ...(allowlistHashValue !== undefined
                 ? { allowlistHash: allowlistHashValue }
                 : {}),
@@ -246,6 +248,7 @@ export class MajikSignatureEmbed {
             contentType: options?.contentType,
             timestamp: options?.timestamp,
             expectedSigners: options?.expectedSigners,
+            validUntil: options?.validUntil,
         }, debug);
         const sig = envelope.findSignature(key.fingerprint);
         if (!sig) {
@@ -329,7 +332,7 @@ export class MajikSignatureEmbed {
                 },
             ];
         }
-        return MajikSignatureEmbed._verifySignatures(envelope, originalBytes, publicKeys, MajikSig, handler.name, options?.expectedSignerId);
+        return MajikSignatureEmbed._verifySignatures(envelope, originalBytes, publicKeys, MajikSig, handler.name, options?.expectedSignerId, options?.now);
     }
     // ── verifyWithKey ──────────────────────────────────────────────────────────
     static async verifyWithKey(file, key, MajikSig, options, debug = false) {
@@ -342,7 +345,8 @@ export class MajikSignatureEmbed {
      * Still strips the file in case it also contains an embedded envelope,
      * ensuring verification runs against the clean original bytes.
      */
-    static async verifyDetached(file, envelopeInput, publicKeys, MajikSig, options, debug = false) {
+    static async verifyDetached(file, envelopeInput, publicKeys, MajikSig, options, // FIX
+    debug = false) {
         const { bytes, handler } = await MajikSignatureEmbed._prepare(file, options);
         const envelope = await MajikSignatureEnvelope.from(envelopeInput);
         const originalBytes = await handler.strip(bytes);
@@ -359,7 +363,7 @@ export class MajikSignatureEmbed {
                 },
             ];
         }
-        return MajikSignatureEmbed._verifySignatures(envelope, originalBytes, publicKeys, MajikSig, handler.name, options?.expectedSignerId);
+        return MajikSignatureEmbed._verifySignatures(envelope, originalBytes, publicKeys, MajikSig, handler.name, options?.expectedSignerId, options?.now);
     }
     // ── verifyDetachedWithKey ──────────────────────────────────────────────────
     static async verifyDetachedWithKey(file, envelopeInput, key, MajikSig, options, debug = false) {
@@ -425,7 +429,7 @@ export class MajikSignatureEmbed {
                 });
                 continue;
             }
-            const verifyResults = MajikSignatureEmbed._verifySignatures(envelope, originalBytes, publicKeys, MajikSig, "mjksmap", options?.expectedSignerId);
+            const verifyResults = MajikSignatureEmbed._verifySignatures(envelope, originalBytes, publicKeys, MajikSig, "mjksmap", options?.expectedSignerId, options?.now);
             const allValid = verifyResults.every((r) => r.valid);
             results.push({
                 path: file.path,
@@ -667,7 +671,7 @@ export class MajikSignatureEmbed {
      * verify each remaining signature, and stamp the handler name onto each
      * result. Previously duplicated near-verbatim in both methods.
      */
-    static _verifySignatures(envelope, originalBytes, publicKeys, MajikSig, handlerName, expectedSignerId) {
+    static _verifySignatures(envelope, originalBytes, publicKeys, MajikSig, handlerName, expectedSignerId, now) {
         const sigsToVerify = expectedSignerId
             ? envelope.signatures.filter((s) => s.signerId === expectedSignerId)
             : envelope.signatures;
@@ -683,7 +687,7 @@ export class MajikSignatureEmbed {
             ];
         }
         return sigsToVerify.map((sig) => ({
-            ...MajikSig.verify(originalBytes, sig, publicKeys),
+            ...MajikSig.verify(originalBytes, sig, publicKeys, now),
             handler: handlerName,
         }));
     }

package/dist/core/payload.d.ts

@@ -41,14 +41,16 @@ export interface PayloadFields {
      * Must be omitted entirely (not null) for all other signatures.
      */
     allowlistHash?: string;
+    validUntil?: string;
 }
 /**
  * Build the canonical byte payload that both algorithms sign and verify.
  * Deterministic: identical inputs always produce identical bytes.
  *
- * `alh` is conditionally spread — present only when allowlistHash is provided.
- * This is the load-bearing backward-compat guarantee: old signatures never had
- * `alh` in their payload, so we must not add it (even as null) when verifying them.
+ * `alh` and `vu` are conditionally spread — present only when allowlistHash /
+ * validUntil are provided. This is the load-bearing backward-compat guarantee:
+ * old signatures never had these keys in their payload, so we must not add
+ * them (even as null) when verifying old signatures.
  */
 export declare function buildSigningPayload(fields: PayloadFields): Uint8Array;
 export declare function buildTSACanonicalBytes(payload: MajikTSAPayload): Uint8Array;

package/dist/core/payload.js

@@ -29,14 +29,15 @@
  *   payload bytes identical to what pre-multi-sig signers produced, so all
  *   existing signatures continue to verify correctly.
  */
-import { MAJIK_SIGNATURE_DOMAIN, MAJIK_SIGNATURE_VERSION, MAJIK_TSA_DOMAIN } from "./constants";
+import { MAJIK_SIGNATURE_DOMAIN, MAJIK_SIGNATURE_VERSION, MAJIK_TSA_DOMAIN, } from "./constants";
 /**
  * Build the canonical byte payload that both algorithms sign and verify.
  * Deterministic: identical inputs always produce identical bytes.
  *
- * `alh` is conditionally spread — present only when allowlistHash is provided.
- * This is the load-bearing backward-compat guarantee: old signatures never had
- * `alh` in their payload, so we must not add it (even as null) when verifying them.
+ * `alh` and `vu` are conditionally spread — present only when allowlistHash /
+ * validUntil are provided. This is the load-bearing backward-compat guarantee:
+ * old signatures never had these keys in their payload, so we must not add
+ * them (even as null) when verifying old signatures.
  */
 export function buildSigningPayload(fields) {
     const meta = JSON.stringify({
@@ -50,6 +51,9 @@ export function buildSigningPayload(fields) {
         ...(fields.allowlistHash !== undefined
             ? { alh: fields.allowlistHash }
             : {}),
+        // Conditionally include vu — same reasoning: omit entirely so all
+        // pre-expiry signatures reproduce byte-identical payloads (backward compat).
+        ...(fields.validUntil !== undefined ? { vu: fields.validUntil } : {}),
     });
     const prefix = new TextEncoder().encode(MAJIK_SIGNATURE_DOMAIN);
     const body = new TextEncoder().encode(meta);

package/dist/core/types.d.ts

@@ -2,12 +2,14 @@
  * types.ts
  * Public types for the MajikSignature library.
  */
-import { ISODateString } from "@majikah/majik-key";
-import { MajikChainAnchor } from "../anchor/types";
+import type { ISODateString, MajikKeyFingerprint } from "@majikah/majik-key";
+import type { MajikChainAnchor } from "../anchor/types";
 import type { ContentType } from "./constants";
 import type { MajikSignatureEnvelope } from "./envelope";
 export type { ContentType };
 export type MajikSignatureEnvelopeJSON = MultiSigEnvelope;
+export type ED25519Signature = string;
+export type MLDSA87Signature = string;
 /**
  * The serializable per-signer signature envelope.
  * Everything a verifier needs — no private keys required.
@@ -16,7 +18,7 @@ export interface MajikSignatureJSON {
     /** Envelope version — must equal MAJIK_SIGNATURE_VERSION */
     version: 1;
     /** MajikKey fingerprint (SHA-256 of X25519 public key, base64) */
-    signerId: string;
+    signerId: MajikKeyFingerprint;
     /** Ed25519 public key, base64 (32 bytes) */
     signerEdPublicKey: string;
     /** ML-DSA-87 public key, base64 (2592 bytes) */
@@ -26,11 +28,11 @@ export interface MajikSignatureJSON {
     /** Advisory content type — e.g. "audio/wav", "application/pdf" */
     contentType?: string;
     /** ISO 8601 timestamp of when the signature was created */
-    timestamp: string;
+    timestamp: ISODateString;
     /** Ed25519 signature over the canonical payload, base64 (64 bytes) */
-    edSignature: string;
+    edSignature: ED25519Signature;
     /** ML-DSA-87 signature over the canonical payload, base64 (4595 bytes) */
-    mlDsaSignature: string;
+    mlDsaSignature: MLDSA87Signature;
     /**
      * SHA-256 hash of the canonical allowlist JSON, base64 (44 chars).
      * Present only on the envelope of the signer who established the allowlist.
@@ -39,6 +41,14 @@ export interface MajikSignatureJSON {
      * Absent on all other signers and on any signature made before multi-sig support.
      */
     allowlistHash?: string;
+    /**
+     * Optional ISO 8601 expiry. When present, verify() treats the signature
+     * as invalid once the current time is past this value. Absent = never
+     * expires (matches all pre-existing signatures — fully backward compatible).
+     * Covered by the canonical signing payload when present, so it cannot be
+     * stripped or extended post-hoc without breaking both signatures.
+     */
+    validUntil?: ISODateString;
     tsa?: MajikTimestamp;
 }
 export interface MajikTSAPayload {
@@ -65,13 +75,14 @@ export interface MajikTSAPayload {
  */
 export interface MajikSignatureCompactJSON {
     v: 1;
-    signerId: string;
+    signerId: MajikKeyFingerprint;
     contentHash: string;
     contentType?: string;
-    timestamp: string;
-    edSignature: string;
-    mlDsaSignature: string;
+    timestamp: ISODateString;
+    edSignature: ED25519Signature;
+    mlDsaSignature: MLDSA87Signature;
     allowlistHash?: string;
+    validUntil?: ISODateString;
 }
 export interface MajikTSARequest {
     digest: {
@@ -91,7 +102,7 @@ export interface MajikTimestamp {
  */
 export interface ExpectedSigner {
     /** MajikKey fingerprint (SHA-256 of X25519 public key, base64) */
-    signerId: string;
+    signerId: MajikKeyFingerprint;
     /** Ed25519 public key, base64 (32 bytes) */
     edPublicKey: string;
     /** ML-DSA-87 public key, base64 (2592 bytes) */
@@ -123,7 +134,7 @@ export interface MultiSigEnvelope {
      * their signature verification.
      * Absent when allowlist is absent.
      */
-    allowlistSignerId?: string;
+    allowlistSignerId?: MajikKeyFingerprint;
     /** All per-signer envelopes. One entry per signer, keyed logically by signerId. */
     signatures: MajikSignatureJSON[];
     /**
@@ -137,7 +148,7 @@ export interface MultiSigEnvelope {
      * ISO 8601 timestamp of when the seal was applied.
      * Included in the seal hash input — changing this breaks the seal.
      */
-    sealTimestamp?: string;
+    sealTimestamp?: ISODateString;
     /**
      * Fingerprint of the signer who applied the seal.
      * Must equal allowlistSignerId — only the issuer can seal.
@@ -151,7 +162,7 @@ export interface MultiSigEnvelope {
  */
 export interface MajikSignerPublicKeys {
     /** MajikKey fingerprint */
-    signerId: string;
+    signerId: MajikKeyFingerprint;
     /** Ed25519 public key bytes (32 bytes) */
     edPublicKey: Uint8Array;
     /** ML-DSA-87 public key bytes (2592 bytes) */
@@ -164,7 +175,7 @@ export interface SignOptions {
     /** Advisory content type label */
     contentType?: string;
     /** Override timestamp (useful for deterministic tests) */
-    timestamp?: string;
+    timestamp?: ISODateString;
     /**
      * Restrict future signers to these keys only.
      * Only honoured when this is the first signature on a file (no existing
@@ -173,20 +184,28 @@ export interface SignOptions {
      * Each entry must include signerId + edPublicKey + mlDsaPublicKey (base64).
      */
     expectedSigners?: ExpectedSigner[];
+    /**
+     * ISO 8601 timestamp. If set, verify() will fail with an "expired" reason
+     * once the current time passes this value. Optional — omit for a
+     * signature that never expires.
+     */
+    validUntil?: string;
 }
 /**
  * Result returned by MajikSignature.verify() and all file-level verify methods.
  */
 export interface VerificationResult {
     valid: boolean;
-    signerId?: string;
+    signerId?: MajikKeyFingerprint;
     contentHash?: string;
-    timestamp: string;
+    timestamp: ISODateString;
     contentType?: string;
     /** Present when result came from a file verify — which handler processed it */
     handler?: string;
     /** Present when valid is false — human-readable failure reason */
     reason?: string;
+    /** True only when the sole reason valid=false is expiry (crypto checked out fine). */
+    expired?: boolean;
 }
 /**
  * Result returned by verifySeal().
@@ -195,7 +214,7 @@ export interface SealVerificationResult {
     /** Whether the seal hash is valid and matches all current signatories */
     valid: boolean;
     /** Fingerprint of who sealed the envelope */
-    sealedBy?: string;
+    sealedBy?: MajikKeyFingerprint;
     /** ISO 8601 timestamp of when the seal was applied */
     sealTimestamp?: string;
     /** Human-readable failure reason when valid is false */
@@ -209,9 +228,9 @@ export interface SealInfo {
     /** SHA3-512 hash of the canonical seal payload, hex-encoded (128 chars) */
     sealHash: string;
     /** ISO 8601 timestamp of when the seal was applied */
-    sealTimestamp: string;
+    sealTimestamp: ISODateString;
     /** Fingerprint of the issuer who applied the seal */
-    sealedBy: string;
+    sealedBy: MajikKeyFingerprint;
 }
 /**
  * Full information about a single signatory.
@@ -219,7 +238,7 @@ export interface SealInfo {
  */
 export interface SignatoryInfo {
     /** MajikKey fingerprint */
-    signerId: string;
+    signerId: MajikKeyFingerprint;
     /** Ed25519 public key, base64 */
     edPublicKey: string;
     /** ML-DSA-87 public key, base64 */
@@ -227,7 +246,7 @@ export interface SignatoryInfo {
     /** Whether this signatory has already signed */
     hasSigned: boolean;
     /** ISO 8601 timestamp of their signature — present only when hasSigned is true */
-    signedAt?: string;
+    signedAt?: ISODateString;
 }
 /**
  * Result returned by getSignatories() and its aliases.
@@ -357,8 +376,14 @@ export interface BatchFileInput {
 }
 export interface BatchSignOptions {
     contentType?: string;
-    timestamp?: string;
+    timestamp?: ISODateString;
     expectedSigners?: ExpectedSigner[];
+    /**
+     * ISO 8601 expiry applied to every signature in the batch. Optional —
+     * omit for signatures that never expire. Same field, same semantics as
+     * SignOptions.validUntil, just applied uniformly across the batch.
+     */
+    validUntil?: ISODateString;
     /** "map" (default) produces one MajikSignatureMap covering the whole
      *  batch. "separate" produces one .mjksig Blob per file. */
     mode?: "map" | "separate";
@@ -405,7 +430,12 @@ export interface FileVerifyResult {
     relocatedFrom?: string;
 }
 export interface BatchVerifyOptions {
-    expectedSignerId?: string;
+    expectedSignerId?: MajikKeyFingerprint;
+    /**
+     * Time to check validUntil against. Defaults to the current time.
+     * Every per-file verification in the batch uses this same value.
+     */
+    now?: Date;
     /**
      * If true, a file with status "not_in_map" is a hard error for the whole
      * batch call (throws). Default false — missing files are reported per-file

package/dist/core/validator.d.ts

@@ -2,6 +2,7 @@
  * validator.ts
  * Input validation and assertion helpers for MajikSignature.
  */
+import { ISODateString } from "@majikah/majik-key";
 import type { ExpectedSigner, MajikSignatureJSON, MajikSignerPublicKeys, MajikTimestamp, MajikTSAPayload, MultiSigEnvelope } from "./types";
 export declare class MajikSignatureValidator {
     static assert(condition: unknown, message: string, field?: string): asserts condition;
@@ -22,6 +23,7 @@ export declare class MajikSignatureValidator {
      */
     static validateSeal(env: MultiSigEnvelope): void;
     static validateSealHash(hash: string): void;
+    static validateValidUntil(value: ISODateString | undefined): void;
     static validateMultiSigEnvelope(env: unknown): asserts env is MultiSigEnvelope;
     static validateMajikTSAPayload(payload: unknown): asserts payload is MajikTSAPayload;
     static validateMajikTimestamp(tsa: unknown): asserts tsa is MajikTimestamp;

package/dist/core/validator.js

@@ -153,6 +153,13 @@ export class MajikSignatureValidator {
         if (typeof hash !== "string" || hash.length !== SEAL_HASH_HEX_LEN)
             throw new MajikSignatureValidationError(`sealHash must be exactly ${SEAL_HASH_HEX_LEN} hex chars (SHA3-512)`, "sealHash");
     }
+    static validateValidUntil(value) {
+        if (value === undefined)
+            return;
+        if (typeof value !== "string" || Number.isNaN(Date.parse(value))) {
+            throw new MajikSignatureValidationError("validUntil must be a valid ISO 8601 timestamp string", "validUntil");
+        }
+    }
     // ── MultiSigEnvelope validator ───────────────────────────────────────────────
     static validateMultiSigEnvelope(env) {
         if (typeof env !== "object" || env === null)

package/dist/majik-signature.d.ts

@@ -3,8 +3,8 @@
  * MajikSignature — hybrid Ed25519 + ML-DSA-87 content signing and verification.
  *
  */
-import type { MajikKey } from "@majikah/majik-key";
-import type { BatchFileInput, BatchSignOptions, BatchVerifyInput, BatchVerifyOptions, EnvelopeInfo, ExpectedSigner, FileVerifyResult, MajikSignatureCompactJSON, MajikSignatureEnvelopeJSON, MajikSignatureJSON, MajikSignerPublicKeys, MajikTimestamp, MajikTSARequest, SealInfo, SealVerificationResult, SignatoriesFilter, SignatoriesResult, SignatoryInfo, SignOptions, VerificationResult } from "./core/types";
+import type { ISODateString, MajikKey, MajikKeyFingerprint } from "@majikah/majik-key";
+import type { BatchFileInput, BatchSignOptions, BatchVerifyInput, BatchVerifyOptions, ED25519Signature, EnvelopeInfo, ExpectedSigner, FileVerifyResult, MajikSignatureCompactJSON, MajikSignatureEnvelopeJSON, MajikSignatureJSON, MajikSignerPublicKeys, MajikTimestamp, MajikTSARequest, MLDSA87Signature, SealInfo, SealVerificationResult, SignatoriesFilter, SignatoriesResult, SignatoryInfo, SignOptions, VerificationResult } from "./core/types";
 import { MajikSignatureEmbed } from "./core/embed/majik-embed";
 import type { ImageVerificationResult, ImageSignOptions, ImageSignatureStub } from "./core/stamp";
 import { MajikChainAnchor, MajikChainAnchorMemo } from "./anchor/types";
@@ -42,10 +42,21 @@ import { SignatureOrderResult } from "./core/order";
  *   - Sealing computes a SHA3-512 hash over all current signatories + timestamp
  *   - A sealed envelope rejects all further signing attempts
  *
+ * Expiry:
+ *   - A signer may optionally set validUntil (ISO 8601) when signing
+ *   - Cryptographically committed to via the canonical payload — the field
+ *     cannot be added, stripped, or extended post-hoc without breaking both
+ *     Ed25519 and ML-DSA-87
+ *   - verify() checks expiry only AFTER both signatures pass, so an
+ *     expired-but-forged signature is reported as invalid, not "expired"
+ *   - Absent = never expires, matching every signature that predates this
+ *     feature — fully backward compatible, no migration needed
+ *
  * Canonical payload:
- *   "majik-signature-v1:" + JSON({ v, id, ts, ct, hash[, alh] })
- *   where hash = SHA-256(content), alh = SHA-256(canonical allowlist) — omitted
- *   when no allowlist is set, preserving backward compat with old signatures.
+ *   "majik-signature-v1:" + JSON({ v, id, ts, ct, hash[, alh][, vu] })
+ *   where hash = SHA-256(content), alh = SHA-256(canonical allowlist), and
+ *   vu = validUntil — each omitted (not nulled) when unset, preserving
+ *   backward compat with signatures made before that field existed.
  */
 export declare class MajikSignature {
     private readonly _version;
@@ -58,30 +69,50 @@ export declare class MajikSignature {
     private readonly _edSignature;
     private readonly _mlDsaSignature;
     private readonly _allowlistHash?;
+    private readonly _validUntil?;
     private _tsa?;
     private constructor();
     get version(): 1;
-    get signerId(): string;
+    get signerId(): MajikKeyFingerprint;
     get signerEdPublicKey(): string;
     get signerMlDsaPublicKey(): string;
     get contentHash(): string;
     get contentType(): string | undefined;
-    get timestamp(): string;
-    get edSignature(): string;
-    get mlDsaSignature(): string;
+    get timestamp(): ISODateString;
+    get edSignature(): ED25519Signature;
+    get mlDsaSignature(): MLDSA87Signature;
     /**
      * SHA-256 hash of the canonical allowlist, base64.
      * Present only on the envelope of the signer who established the allowlist.
      * Undefined on all other signers and on pre-allowlist signatures.
      */
     get allowlistHash(): string | undefined;
+    /**
+     * ISO 8601 timestamp after which this signature is considered expired by
+     * verify(). Undefined means the signature never expires — this is the case
+     * for every signature created before expiry support existed.
+     */
+    get validUntil(): ISODateString | undefined;
     get tsa(): MajikTimestamp | undefined;
+    /**
+     * Structural expiry check against this signature's validUntil — does NOT
+     * verify the cryptographic signature. Always false when validUntil is unset.
+     * Use verify() for a full trust decision; use this for a quick UI-facing
+     * "is this stale" check without needing the original content or public keys.
+     *
+     * @param now - Time to check against. Defaults to the current time.
+     */
+    isExpired(now?: Date): boolean;
     /**
      * Sign content with an unlocked MajikKey.
      *
      * Both Ed25519 and ML-DSA-87 sign the same canonical payload.
      * When options.allowlistHash is provided (injected internally by signAndEmbed),
      * it is included in the payload so both algorithms cover the allowlist.
+     * When options.validUntil is provided, it is likewise included in the payload
+     * so both algorithms cover the expiry — a verifier cannot strip or extend it
+     * without invalidating the signature. Omit it for a signature that never
+     * expires.
      */
     static sign(content: Uint8Array | string, key: MajikKey, options?: SignOptions & {
         allowlistHash?: string;
@@ -89,8 +120,20 @@ export declare class MajikSignature {
     /**
      * Verify a MajikSignature against content and the signer's public keys.
      * Both Ed25519 AND ML-DSA-87 must verify — if either fails, returns invalid.
+     *
+     * If the envelope carries a validUntil, expiry is checked only after both
+     * signatures have already passed — so a forged-but-expired signature is
+     * reported as an invalid signature (wrong reason), never mistaken for a
+     * merely-expired-but-otherwise-valid one. A signature with no validUntil
+     * never expires.
+     *
+     * @param now - Time to check expiry against. Defaults to the current time;
+     *   override for deterministic tests or to verify "as of" a past/future moment.
+     * @returns valid: false with reason "Signature expired at ..." and
+     *   expired: true when the only failure is expiry; expired is omitted
+     *   otherwise.
      */
-    static verify(content: Uint8Array | string, signature: MajikSignature | MajikSignatureJSON, publicKeys: MajikSignerPublicKeys): VerificationResult;
+    static verify(content: Uint8Array | string, signature: MajikSignature | MajikSignatureJSON, publicKeys: MajikSignerPublicKeys, now?: Date): VerificationResult;
     validate(): void;
     isValid(): boolean;
     extractPublicKeys(): MajikSignerPublicKeys;
@@ -121,12 +164,19 @@ export declare class MajikSignature {
      * Non-allowlisted signers are rejected before any crypto (MajikSignatureAllowlistError).
      * Sealed files are always rejected.
      *
+     * Pass options.validUntil (ISO 8601) to make this specific signature expire —
+     * cryptographically bound into the payload, so it cannot be stripped or
+     * extended without invalidating the signature. Omit for a signature that
+     * never expires. In multi-sig files, expiry is per-signer: each signer's
+     * validUntil (or absence of one) applies only to their own entry.
+     *
      * @example
      *   const { blob } = await MajikSignature.signFile(file, aliceKey, {
      *     expectedSigners: [
      *       MajikSignature.expectedSignerFromKey(aliceKey),
      *       MajikSignature.expectedSignerFromKey(bobKey),
      *     ],
+     *     validUntil: "2027-01-01T00:00:00.000Z",
      *   });
      */
     static signFile(file: Blob, key: MajikKey, options?: {
@@ -134,6 +184,7 @@ export declare class MajikSignature {
         timestamp?: string;
         mimeType?: string;
         expectedSigners?: ExpectedSigner[];
+        validUntil?: string;
     }): ReturnType<typeof MajikSignatureEmbed.signAndEmbed<MajikSignature>>;
     /**
      * Sign a file and return the signature envelope detached.
@@ -146,10 +197,15 @@ export declare class MajikSignature {
      * it's added to the envelope — the digest-match and TSA-signature checks
      * happen automatically inside addTSA().
      *
+     * Pass options.validUntil (ISO 8601) to make this signature expire — see
+     * signFile() for the same semantics; identical here since both funnel
+     * through the same underlying sign() call.
+     *
      * @example
      *   const { blob, envelope, signature } = await MajikSignature.signFileDetached(file, aliceKey, {
-     *     existingEnvelope: outOfBandEnvelope, // Optionally pass state from an external source
-     *     tsa: myTsaTimestamp, // Optionally attach a Trusted Timestamp
+     *     existingEnvelope: outOfBandEnvelope,
+     *     tsa: myTsaTimestamp,
+     *     validUntil: "2027-01-01T00:00:00.000Z",
      *   });
      *   console.log(signature.hasTSA); // true if tsa was provided and accepted
      */
@@ -158,6 +214,7 @@ export declare class MajikSignature {
         timestamp?: string;
         mimeType?: string;
         expectedSigners?: ExpectedSigner[];
+        validUntil?: string;
         existingEnvelope?: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob;
         tsa?: MajikTimestamp;
     }): ReturnType<typeof MajikSignatureEmbed.signDetached<MajikSignature>>;
@@ -167,6 +224,10 @@ export declare class MajikSignature {
      * batch (default — meant to sit at the root of the zip as one .mjksmap),
      * or as separate .mjksig Blobs per file when options.mode === "separate".
      *
+     * options.validUntil, if set, is applied identically to every signature in
+     * the batch — there is no per-file override. Sign files individually via
+     * signFileDetached() if different files need different expiries.
+     *
      * @example
      *   const result = await MajikSignature.signBatchDetached(
      *     [
@@ -174,6 +235,7 @@ export declare class MajikSignature {
      *       { path: "docs/appendix.pdf", blob: appendixBlob },
      *     ],
      *     aliceKey,
+     *     { validUntil: "2027-01-01T00:00:00.000Z" },
      *   );
      *   if (result.mode === "map") {
      *     zip.file("signatures.mjksmap", await result.mapBlob.arrayBuffer());
@@ -184,20 +246,27 @@ export declare class MajikSignature {
      * Verify a file's embedded signatures.
      * Returns one VerificationResult per signer. Old single-sig files return a single-item array.
      * Pass options.expectedSignerId to verify only a specific signer.
+     * Pass options.now to check expiry as of a specific time instead of the
+     * current time. Any signer whose validUntil has passed comes back with
+     * valid: false, expired: true, and a reason noting the expiry.
      */
     static verifyFile(file: Blob, keyOrPublicKeys: MajikKey | MajikSignerPublicKeys, options?: {
         expectedSignerId?: string;
         mimeType?: string;
+        now?: Date;
     }, debug?: boolean): Promise<VerificationResult[]>;
     /**
      * Verify a file against a detached signature envelope.
      * Skips extraction and verifies the stripped file bytes directly against the provided envelope.
      * Returns one VerificationResult per signer.
      * Pass options.expectedSignerId to verify only a specific signer.
+     * Pass options.now to check expiry as of a specific time instead of the
+     * current time.
      */
     static verifyFileDetached(file: Blob, envelope: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob, keyOrPublicKeys: MajikKey | MajikSignerPublicKeys, options?: {
         expectedSignerId?: string;
         mimeType?: string;
+        now?: Date;
     }, debug?: boolean): Promise<VerificationResult[]>;
     /**
      * Verify a batch of extracted files against a MajikSignatureMap (loaded via
@@ -205,6 +274,11 @@ export declare class MajikSignature {
      * throwing — a missing, tampered, or invalidly-signed file is a normal
      * possible outcome to display, not an exceptional one to catch.
      *
+     * A file whose signature has passed its validUntil comes back with
+     * status "invalid" and results[].expired === true — same status as any
+     * other failed signature, so summarizeBatchVerification()'s allValid check
+     * still works unchanged. Pass options.now to check "as of" a specific time.
+     *
      * @example
      *   const map = await MajikSignatureMap.fromMJKSMAP(mjksmapBlob);
      *   const results = await MajikSignature.verifyFilesFromMjksMap(
@@ -505,12 +579,21 @@ export declare class MajikSignature {
      * The verifier must supply the signer's public keys out-of-band via
      * fromCompact() / verifyCompact() — never trust keys recovered from the
      * compact payload itself, because there are none.
+     *
+     * allowlistHash and validUntil, when present, carry over unchanged — both
+     * are already part of what was signed, so compacting doesn't affect their
+     * enforcement.
      */
     toCompact(): MajikSignatureCompactJSON;
     /**
      * Rehydrate a full MajikSignature from a compact payload + externally
      * resolved public keys. Throws if signerId doesn't match the supplied keys —
      * this is a cheap sanity check, not a substitute for verify().
+     *
+     * allowlistHash and validUntil are carried through unchanged from the
+     * compact payload; verify() will still enforce them via the recomputed
+     * canonical payload, so an out-of-band edit to either field here would
+     * simply fail verification rather than being silently trusted.
      */
     static fromCompact(compact: MajikSignatureCompactJSON, publicKeys: Pick<MajikSignerPublicKeys, "edPublicKey" | "mlDsaPublicKey">): MajikSignature;
     /**
@@ -518,6 +601,11 @@ export declare class MajikSignature {
      * publicKeys.signerId before any crypto runs, so a mismatched lookup fails
      * fast with a clear reason instead of a cryptic signature failure.
      *
+     * Delegates to verify() after rehydration, so allowlistHash and validUntil
+     * (when present in the compact payload) are enforced identically to the
+     * full-envelope path — including the "expired" reason/flag on a signature
+     * past its validUntil.
+     *
      * @example
      *   const keys = await resolvePublicKeysForMuid(slink.muid); // your registry
      *   const result = MajikSignature.verifyCompact(canonical, slink.signatureJSON, keys);

package/dist/majik-signature.js

@@ -46,10 +46,21 @@ const secureFill = Uint8Array.prototype.fill;
  *   - Sealing computes a SHA3-512 hash over all current signatories + timestamp
  *   - A sealed envelope rejects all further signing attempts
  *
+ * Expiry:
+ *   - A signer may optionally set validUntil (ISO 8601) when signing
+ *   - Cryptographically committed to via the canonical payload — the field
+ *     cannot be added, stripped, or extended post-hoc without breaking both
+ *     Ed25519 and ML-DSA-87
+ *   - verify() checks expiry only AFTER both signatures pass, so an
+ *     expired-but-forged signature is reported as invalid, not "expired"
+ *   - Absent = never expires, matching every signature that predates this
+ *     feature — fully backward compatible, no migration needed
+ *
  * Canonical payload:
- *   "majik-signature-v1:" + JSON({ v, id, ts, ct, hash[, alh] })
- *   where hash = SHA-256(content), alh = SHA-256(canonical allowlist) — omitted
- *   when no allowlist is set, preserving backward compat with old signatures.
+ *   "majik-signature-v1:" + JSON({ v, id, ts, ct, hash[, alh][, vu] })
+ *   where hash = SHA-256(content), alh = SHA-256(canonical allowlist), and
+ *   vu = validUntil — each omitted (not nulled) when unset, preserving
+ *   backward compat with signatures made before that field existed.
  */
 export class MajikSignature {
     _version;
@@ -62,6 +73,7 @@ export class MajikSignature {
     _edSignature;
     _mlDsaSignature;
     _allowlistHash;
+    _validUntil;
     _tsa;
     constructor(data) {
         this._version = data.version;
@@ -74,6 +86,7 @@ export class MajikSignature {
         this._edSignature = data.edSignature;
         this._mlDsaSignature = data.mlDsaSignature;
         this._allowlistHash = data.allowlistHash;
+        this._validUntil = data.validUntil;
         this._tsa = data.tsa;
     }
     // ── Getters ─────────────────────────────────────────────────────────────────
@@ -112,9 +125,29 @@ export class MajikSignature {
     get allowlistHash() {
         return this._allowlistHash;
     }
+    /**
+     * ISO 8601 timestamp after which this signature is considered expired by
+     * verify(). Undefined means the signature never expires — this is the case
+     * for every signature created before expiry support existed.
+     */
+    get validUntil() {
+        return this._validUntil;
+    }
     get tsa() {
         return this._tsa;
     }
+    /**
+     * Structural expiry check against this signature's validUntil — does NOT
+     * verify the cryptographic signature. Always false when validUntil is unset.
+     * Use verify() for a full trust decision; use this for a quick UI-facing
+     * "is this stale" check without needing the original content or public keys.
+     *
+     * @param now - Time to check against. Defaults to the current time.
+     */
+    isExpired(now = new Date()) {
+        return (this._validUntil !== undefined &&
+            now.getTime() > Date.parse(this._validUntil));
+    }
     // ── SIGN ────────────────────────────────────────────────────────────────────
     /**
      * Sign content with an unlocked MajikKey.
@@ -122,11 +155,16 @@ export class MajikSignature {
      * Both Ed25519 and ML-DSA-87 sign the same canonical payload.
      * When options.allowlistHash is provided (injected internally by signAndEmbed),
      * it is included in the payload so both algorithms cover the allowlist.
+     * When options.validUntil is provided, it is likewise included in the payload
+     * so both algorithms cover the expiry — a verifier cannot strip or extend it
+     * without invalidating the signature. Omit it for a signature that never
+     * expires.
      */
     static async sign(content, key, options, debug = false) {
         MajikSignatureValidator.validateContent(content);
         MajikSignatureValidator.assertDefined(key, "key");
         MajikSignatureValidator.validateContentType(options?.contentType);
+        MajikSignatureValidator.validateValidUntil(options?.validUntil);
         if (key.isLocked)
             throw new MajikSignatureKeyError("MajikKey is locked. Call unlock() before signing.");
         if (!key.hasSigningKeys)
@@ -148,12 +186,14 @@ export class MajikSignature {
             const signerId = key.fingerprint;
             const contentType = options?.contentType;
             const allowlistHash = options?.allowlistHash;
+            const validUntil = options?.validUntil; // NEW
             const payload = buildSigningPayload({
                 signerId,
                 timestamp,
                 contentHash,
                 contentType,
                 allowlistHash,
+                validUntil,
             });
             if (debug)
                 console.log("Signing Payload:", payload);
@@ -175,6 +215,7 @@ export class MajikSignature {
                 edSignature: bytesToBase64(edSigBytes),
                 mlDsaSignature: bytesToBase64(mlDsaSigBytes),
                 ...(allowlistHash !== undefined ? { allowlistHash } : {}),
+                ...(validUntil !== undefined ? { validUntil } : {}), // NEW
             };
             return new MajikSignature(envelope);
         }
@@ -201,8 +242,20 @@ export class MajikSignature {
     /**
      * Verify a MajikSignature against content and the signer's public keys.
      * Both Ed25519 AND ML-DSA-87 must verify — if either fails, returns invalid.
+     *
+     * If the envelope carries a validUntil, expiry is checked only after both
+     * signatures have already passed — so a forged-but-expired signature is
+     * reported as an invalid signature (wrong reason), never mistaken for a
+     * merely-expired-but-otherwise-valid one. A signature with no validUntil
+     * never expires.
+     *
+     * @param now - Time to check expiry against. Defaults to the current time;
+     *   override for deterministic tests or to verify "as of" a past/future moment.
+     * @returns valid: false with reason "Signature expired at ..." and
+     *   expired: true when the only failure is expiry; expired is omitted
+     *   otherwise.
      */
-    static verify(content, signature, publicKeys) {
+    static verify(content, signature, publicKeys, now = new Date()) {
         try {
             MajikSignatureValidator.validateContent(content);
             MajikSignatureValidator.validateSignerPublicKeys(publicKeys);
@@ -226,6 +279,7 @@ export class MajikSignature {
                 contentHash: env.contentHash,
                 contentType: env.contentType,
                 allowlistHash: env.allowlistHash,
+                validUntil: env.validUntil,
             });
             let edOk;
             try {
@@ -247,6 +301,14 @@ export class MajikSignature {
             }
             if (!mlDsaOk)
                 return invalid("Invalid ML-DSA-87 signature");
+            // NEW — expiry check, only after crypto has checked out
+            if (env.validUntil !== undefined &&
+                now.getTime() > Date.parse(env.validUntil)) {
+                return {
+                    ...invalid(`Signature expired at ${env.validUntil} (verified at ${now.toISOString()})`),
+                    expired: true,
+                };
+            }
             return {
                 valid: true,
                 signerId: env.signerId,
@@ -304,6 +366,9 @@ export class MajikSignature {
             ...(this._allowlistHash !== undefined
                 ? { allowlistHash: this._allowlistHash }
                 : {}),
+            ...(this._validUntil !== undefined
+                ? { validUntil: this._validUntil }
+                : {}),
             ...(this._tsa !== undefined ? { tsa: this._tsa } : {}),
         };
     }
@@ -394,12 +459,19 @@ export class MajikSignature {
      * Non-allowlisted signers are rejected before any crypto (MajikSignatureAllowlistError).
      * Sealed files are always rejected.
      *
+     * Pass options.validUntil (ISO 8601) to make this specific signature expire —
+     * cryptographically bound into the payload, so it cannot be stripped or
+     * extended without invalidating the signature. Omit for a signature that
+     * never expires. In multi-sig files, expiry is per-signer: each signer's
+     * validUntil (or absence of one) applies only to their own entry.
+     *
      * @example
      *   const { blob } = await MajikSignature.signFile(file, aliceKey, {
      *     expectedSigners: [
      *       MajikSignature.expectedSignerFromKey(aliceKey),
      *       MajikSignature.expectedSignerFromKey(bobKey),
      *     ],
+     *     validUntil: "2027-01-01T00:00:00.000Z",
      *   });
      */
     static async signFile(file, key, options) {
@@ -416,10 +488,15 @@ export class MajikSignature {
      * it's added to the envelope — the digest-match and TSA-signature checks
      * happen automatically inside addTSA().
      *
+     * Pass options.validUntil (ISO 8601) to make this signature expire — see
+     * signFile() for the same semantics; identical here since both funnel
+     * through the same underlying sign() call.
+     *
      * @example
      *   const { blob, envelope, signature } = await MajikSignature.signFileDetached(file, aliceKey, {
-     *     existingEnvelope: outOfBandEnvelope, // Optionally pass state from an external source
-     *     tsa: myTsaTimestamp, // Optionally attach a Trusted Timestamp
+     *     existingEnvelope: outOfBandEnvelope,
+     *     tsa: myTsaTimestamp,
+     *     validUntil: "2027-01-01T00:00:00.000Z",
      *   });
      *   console.log(signature.hasTSA); // true if tsa was provided and accepted
      */
@@ -432,6 +509,10 @@ export class MajikSignature {
      * batch (default — meant to sit at the root of the zip as one .mjksmap),
      * or as separate .mjksig Blobs per file when options.mode === "separate".
      *
+     * options.validUntil, if set, is applied identically to every signature in
+     * the batch — there is no per-file override. Sign files individually via
+     * signFileDetached() if different files need different expiries.
+     *
      * @example
      *   const result = await MajikSignature.signBatchDetached(
      *     [
@@ -439,6 +520,7 @@ export class MajikSignature {
      *       { path: "docs/appendix.pdf", blob: appendixBlob },
      *     ],
      *     aliceKey,
+     *     { validUntil: "2027-01-01T00:00:00.000Z" },
      *   );
      *   if (result.mode === "map") {
      *     zip.file("signatures.mjksmap", await result.mapBlob.arrayBuffer());
@@ -451,6 +533,9 @@ export class MajikSignature {
      * Verify a file's embedded signatures.
      * Returns one VerificationResult per signer. Old single-sig files return a single-item array.
      * Pass options.expectedSignerId to verify only a specific signer.
+     * Pass options.now to check expiry as of a specific time instead of the
+     * current time. Any signer whose validUntil has passed comes back with
+     * valid: false, expired: true, and a reason noting the expiry.
      */
     static async verifyFile(file, keyOrPublicKeys, options, debug = false) {
         if (MajikSignature._isMajikKey(keyOrPublicKeys)) {
@@ -463,6 +548,8 @@ export class MajikSignature {
      * Skips extraction and verifies the stripped file bytes directly against the provided envelope.
      * Returns one VerificationResult per signer.
      * Pass options.expectedSignerId to verify only a specific signer.
+     * Pass options.now to check expiry as of a specific time instead of the
+     * current time.
      */
     static async verifyFileDetached(file, envelope, keyOrPublicKeys, options, debug = false) {
         if (MajikSignature._isMajikKey(keyOrPublicKeys)) {
@@ -476,6 +563,11 @@ export class MajikSignature {
      * throwing — a missing, tampered, or invalidly-signed file is a normal
      * possible outcome to display, not an exceptional one to catch.
      *
+     * A file whose signature has passed its validUntil comes back with
+     * status "invalid" and results[].expired === true — same status as any
+     * other failed signature, so summarizeBatchVerification()'s allValid check
+     * still works unchanged. Pass options.now to check "as of" a specific time.
+     *
      * @example
      *   const map = await MajikSignatureMap.fromMJKSMAP(mjksmapBlob);
      *   const results = await MajikSignature.verifyFilesFromMjksMap(
@@ -816,6 +908,10 @@ export class MajikSignature {
      * The verifier must supply the signer's public keys out-of-band via
      * fromCompact() / verifyCompact() — never trust keys recovered from the
      * compact payload itself, because there are none.
+     *
+     * allowlistHash and validUntil, when present, carry over unchanged — both
+     * are already part of what was signed, so compacting doesn't affect their
+     * enforcement.
      */
     toCompact() {
         return {
@@ -827,12 +923,18 @@ export class MajikSignature {
             edSignature: this._edSignature,
             mlDsaSignature: this._mlDsaSignature,
             allowlistHash: this._allowlistHash,
+            validUntil: this._validUntil,
         };
     }
     /**
      * Rehydrate a full MajikSignature from a compact payload + externally
      * resolved public keys. Throws if signerId doesn't match the supplied keys —
      * this is a cheap sanity check, not a substitute for verify().
+     *
+     * allowlistHash and validUntil are carried through unchanged from the
+     * compact payload; verify() will still enforce them via the recomputed
+     * canonical payload, so an out-of-band edit to either field here would
+     * simply fail verification rather than being silently trusted.
      */
     static fromCompact(compact, publicKeys) {
         if (!publicKeys?.edPublicKey || !publicKeys?.mlDsaPublicKey) {
@@ -849,6 +951,7 @@ export class MajikSignature {
             edSignature: compact.edSignature,
             mlDsaSignature: compact.mlDsaSignature,
             allowlistHash: compact.allowlistHash,
+            validUntil: compact.validUntil,
         };
         return MajikSignature.fromJSON(full);
     }
@@ -857,6 +960,11 @@ export class MajikSignature {
      * publicKeys.signerId before any crypto runs, so a mismatched lookup fails
      * fast with a clear reason instead of a cryptic signature failure.
      *
+     * Delegates to verify() after rehydration, so allowlistHash and validUntil
+     * (when present in the compact payload) are enforced identically to the
+     * full-envelope path — including the "expired" reason/flag on a signature
+     * past its validUntil.
+     *
      * @example
      *   const keys = await resolvePublicKeysForMuid(slink.muid); // your registry
      *   const result = MajikSignature.verifyCompact(canonical, slink.signatureJSON, keys);

package/package.json

@@ -2,7 +2,7 @@
   "name": "@majikah/majik-signature",
   "type": "module",
   "description": "Majik Signature is a hybrid post-quantum content signing and verification library for the Majikah ecosystem. Built on top of Majik Key, it provides tamper-proof, forgery-resistant digital signatures for any content format — using a dual-algorithm architecture that combines classical Ed25519 with post-quantum ML-DSA-87 (FIPS-204).",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",
@@ -52,13 +52,13 @@
   },
   "dependencies": {
     "@majikah/majik-key": "^0.3.4",
-    "@noble/post-quantum": "^0.6.1",
+    "@noble/post-quantum": "^0.7.0",
     "@stablelib/ed25519": "^2.1.0",
     "@stablelib/sha256": "^2.0.1",
     "fflate": "^0.8.3"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.9"
   }