@classytic/primitives 0.27.0 → 0.29.0

package/dist/proration.mjs

@@ -108,6 +108,29 @@ function requirePart(result, id) {
 	return part.amount;
 }
 /**
+* The share of `total` carried by `part` of `whole`, in integer minor units — the VAT on a partial
+* refund, the tax on one tender of a split sale. Largest-remainder rounding, so the share and its
+* complement sum to `total` exactly; `part === whole` returns `total` untouched.
+*
+* @throws ProrationError('INVALID_FRACTION') when an input is not an integer, `whole` is not
+*   positive, or `part` lies outside `[0, whole]` — a refund larger than its payment is a defect
+*   upstream, and clamping it would book a plausible number.
+*/
+function apportion(total, part, whole) {
+	if (![
+		total,
+		part,
+		whole
+	].every(Number.isInteger) || whole <= 0 || part < 0 || part > whole) throw new ProrationError("INVALID_FRACTION", `cannot apportion ${total} by ${part} of ${whole}`);
+	return requirePart(allocate(total, [{
+		id: "part",
+		weight: part
+	}, {
+		id: "rest",
+		weight: whole - part
+	}], "by-weight"), "part");
+}
+/**
 * Allocate the `fraction`-weighted part of a `Money` amount, drift-free — the
 * complement (`1 - fraction`) is discarded but computed so rounding is exact
 * against the whole. `fraction` must be in `[0, 1]`.
@@ -129,4 +152,4 @@ function allocateMoneyByFraction(amount, fraction) {
 	};
 }
 //#endregion
-export { ProrationError, allocateMoneyByFraction, periodProgress, splitByPeriodFraction };
+export { ProrationError, allocateMoneyByFraction, apportion, periodProgress, splitByPeriodFraction };

package/dist/signed-token.d.mts

@@ -0,0 +1,54 @@
+//#region src/security/signed-token.d.ts
+/**
+ * Signed tokens: compact JWS (RFC 7515), ES256 over WebCrypto — a server and an offline device sign
+ * and verify the same bytes with no dependency. Claims follow RFC 7519 (`exp`/`nbf`/`iat` in
+ * seconds).
+ *
+ *   const token = await signToken({ sub, exp }, { kid, privateKey }, { typ: 'till-grant+jwt' });
+ *   const read = await verifyToken<Grant>(token, (kid) => keys.get(kid), { typ: 'till-grant+jwt' });
+ *
+ * `typ` is required on both sides, so one kind of token is never accepted as another, and a token
+ * without `exp` is refused.
+ */
+declare const SIGNED_TOKEN_ALG = "ES256";
+/** A P-256 key as JWK; `d` only on a private key. */
+interface EcJwk {
+  kty?: string;
+  crv?: string;
+  x?: string;
+  y?: string;
+  d?: string;
+  [member: string]: unknown;
+}
+interface SigningKey {
+  /** Published with the public key; names it in each token's header. */
+  readonly kid: string;
+  readonly privateKey: CryptoKey;
+}
+type TokenRefusal = 'malformed' | 'unsupported' | 'wrong_type' | 'unknown_key' | 'bad_signature' | 'no_expiry' | 'expired' | 'not_yet_valid';
+type VerifiedToken<T> = {
+  readonly ok: true;
+  readonly claims: T;
+  readonly kid: string;
+} | {
+  readonly ok: false;
+  readonly reason: TokenRefusal;
+};
+declare function signToken(claims: Record<string, unknown>, key: SigningKey, options: {
+  typ: string;
+}): Promise<string>;
+declare function verifyToken<T>(token: string, keyOf: (kid: string) => CryptoKey | undefined | Promise<CryptoKey | undefined>, options: {
+  typ: string;
+  now?: Date | undefined;
+  leewaySeconds?: number | undefined;
+}): Promise<VerifiedToken<T>>;
+/** A P-256 private JWK as a non-extractable signing key. */
+declare function importSigningKey(privateJwk: EcJwk): Promise<CryptoKey>;
+/** A P-256 public JWK as a verifying key. */
+declare function importVerifyingKey(publicJwk: EcJwk): Promise<CryptoKey>;
+/** The public half of a P-256 private JWK — what is published. */
+declare function publicJwkOf(privateJwk: EcJwk): EcJwk;
+/** A fresh key pair as JWKs — for provisioning a deployment's signing key. */
+declare function generateSigningJwk(): Promise<EcJwk>;
+//#endregion
+export { EcJwk, SIGNED_TOKEN_ALG, SigningKey, TokenRefusal, VerifiedToken, generateSigningJwk, importSigningKey, importVerifyingKey, publicJwkOf, signToken, verifyToken };

package/dist/signed-token.mjs

@@ -0,0 +1,139 @@
+//#region src/security/signed-token.ts
+/**
+* Signed tokens: compact JWS (RFC 7515), ES256 over WebCrypto — a server and an offline device sign
+* and verify the same bytes with no dependency. Claims follow RFC 7519 (`exp`/`nbf`/`iat` in
+* seconds).
+*
+*   const token = await signToken({ sub, exp }, { kid, privateKey }, { typ: 'till-grant+jwt' });
+*   const read = await verifyToken<Grant>(token, (kid) => keys.get(kid), { typ: 'till-grant+jwt' });
+*
+* `typ` is required on both sides, so one kind of token is never accepted as another, and a token
+* without `exp` is refused.
+*/
+const SIGNED_TOKEN_ALG = "ES256";
+const ECDSA = {
+	name: "ECDSA",
+	namedCurve: "P-256"
+};
+const SIGN = {
+	name: "ECDSA",
+	hash: "SHA-256"
+};
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function toBase64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(text) {
+	if (!/^[A-Za-z0-9_-]*$/.test(text)) return null;
+	const binary = atob(text.replace(/-/g, "+").replace(/_/g, "/"));
+	const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+	for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+function parseJson(segment) {
+	const bytes = fromBase64Url(segment);
+	if (!bytes) return null;
+	try {
+		const value = JSON.parse(decoder.decode(bytes));
+		return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+	} catch {
+		return null;
+	}
+}
+async function signToken(claims, key, options) {
+	const input = `${toBase64Url(encoder.encode(JSON.stringify({
+		alg: SIGNED_TOKEN_ALG,
+		typ: options.typ,
+		kid: key.kid
+	})))}.${toBase64Url(encoder.encode(JSON.stringify(claims)))}`;
+	return `${input}.${toBase64Url(new Uint8Array(await crypto.subtle.sign(SIGN, key.privateKey, encoder.encode(input))))}`;
+}
+async function verifyToken(token, keyOf, options) {
+	const parts = typeof token === "string" ? token.split(".") : [];
+	if (parts.length !== 3) return {
+		ok: false,
+		reason: "malformed"
+	};
+	const [headerPart, payloadPart, signaturePart] = parts;
+	const header = parseJson(headerPart);
+	const claims = parseJson(payloadPart);
+	const signature = fromBase64Url(signaturePart);
+	if (!header || !claims || !signature) return {
+		ok: false,
+		reason: "malformed"
+	};
+	if (header.alg !== "ES256" || header.crit !== void 0) return {
+		ok: false,
+		reason: "unsupported"
+	};
+	if (header.typ !== options.typ) return {
+		ok: false,
+		reason: "wrong_type"
+	};
+	if (typeof header.kid !== "string") return {
+		ok: false,
+		reason: "unknown_key"
+	};
+	const key = await keyOf(header.kid);
+	if (!key) return {
+		ok: false,
+		reason: "unknown_key"
+	};
+	if (!await crypto.subtle.verify(SIGN, key, signature, encoder.encode(`${headerPart}.${payloadPart}`))) return {
+		ok: false,
+		reason: "bad_signature"
+	};
+	const now = Math.floor((options.now ?? /* @__PURE__ */ new Date()).getTime() / 1e3);
+	const leeway = options.leewaySeconds ?? 0;
+	if (typeof claims.exp !== "number") return {
+		ok: false,
+		reason: "no_expiry"
+	};
+	if (now >= claims.exp + leeway) return {
+		ok: false,
+		reason: "expired"
+	};
+	if (typeof claims.nbf === "number" && now < claims.nbf - leeway) return {
+		ok: false,
+		reason: "not_yet_valid"
+	};
+	return {
+		ok: true,
+		claims,
+		kid: header.kid
+	};
+}
+/** A P-256 private JWK as a non-extractable signing key. */
+function importSigningKey(privateJwk) {
+	return crypto.subtle.importKey("jwk", privateJwk, ECDSA, false, ["sign"]);
+}
+/** A P-256 public JWK as a verifying key. */
+function importVerifyingKey(publicJwk) {
+	const { kty, crv, x, y } = publicJwk;
+	return crypto.subtle.importKey("jwk", {
+		kty,
+		crv,
+		x,
+		y
+	}, ECDSA, false, ["verify"]);
+}
+/** The public half of a P-256 private JWK — what is published. */
+function publicJwkOf(privateJwk) {
+	const { kty, crv, x, y } = privateJwk;
+	return {
+		kty,
+		crv,
+		x,
+		y
+	};
+}
+/** A fresh key pair as JWKs — for provisioning a deployment's signing key. */
+async function generateSigningJwk() {
+	const pair = await crypto.subtle.generateKey(ECDSA, true, ["sign", "verify"]);
+	return await crypto.subtle.exportKey("jwk", pair.privateKey);
+}
+//#endregion
+export { SIGNED_TOKEN_ALG, generateSigningJwk, importSigningKey, importVerifyingKey, publicJwkOf, signToken, verifyToken };

package/dist/unit-cost-rate.d.mts

@@ -1,4 +1,4 @@
-import { t as MinorUnits, w as CurrencyCode } from "./money-CfAvfNiM.mjs";
+import { O as CurrencyCode, t as MinorUnits } from "./money-C9iLWiWR.mjs";
 //#region src/money/rounded-div.d.ts
 type RoundingMode = 'half-even' | 'half-up';
 //#endregion

package/dist/unit-cost-rate.mjs

@@ -1,4 +1,4 @@
-import { MinorUnits } from "./money.mjs";
+import { t as MinorUnits } from "./money-BBOARE5f.mjs";
 import { t as roundedDiv } from "./rounded-div-BWJb98Ws.mjs";
 //#region src/money/unit-cost-rate.ts
 /** Fixed, ecosystem-wide rate scale: 6 decimal places below the minor unit. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -22,219 +22,293 @@
   },
   "exports": {
     "./money": {
+      "@classytic/source": "./src/money/money.ts",
       "types": "./dist/money.d.mts",
       "default": "./dist/money.mjs"
     },
     "./currency": {
+      "@classytic/source": "./src/money/currency.ts",
       "types": "./dist/currency.d.mts",
       "default": "./dist/currency.mjs"
     },
     "./unit-cost-rate": {
+      "@classytic/source": "./src/money/unit-cost-rate.ts",
       "types": "./dist/unit-cost-rate.d.mts",
       "default": "./dist/unit-cost-rate.mjs"
     },
     "./price-basis": {
+      "@classytic/source": "./src/money/price-basis.ts",
       "types": "./dist/price-basis.d.mts",
       "default": "./dist/price-basis.mjs"
     },
     "./address": {
+      "@classytic/source": "./src/identity/address.ts",
       "types": "./dist/address.d.mts",
       "default": "./dist/address.mjs"
     },
     "./period": {
+      "@classytic/source": "./src/scheduling/period.ts",
       "types": "./dist/period.d.mts",
       "default": "./dist/period.mjs"
     },
     "./calendar": {
+      "@classytic/source": "./src/scheduling/calendar.ts",
       "types": "./dist/calendar.d.mts",
       "default": "./dist/calendar.mjs"
     },
     "./calendar-facts": {
+      "@classytic/source": "./src/scheduling/calendar-facts.ts",
       "types": "./dist/calendar-facts.d.mts",
       "default": "./dist/calendar-facts.mjs"
     },
     "./timezone": {
+      "@classytic/source": "./src/scheduling/timezone.ts",
       "types": "./dist/timezone.d.mts",
       "default": "./dist/timezone.mjs"
     },
     "./reference": {
+      "@classytic/source": "./src/composition/reference.ts",
       "types": "./dist/reference.d.mts",
       "default": "./dist/reference.mjs"
     },
     "./fault-attribution": {
+      "@classytic/source": "./src/composition/fault-attribution.ts",
       "types": "./dist/fault-attribution.d.mts",
       "default": "./dist/fault-attribution.mjs"
     },
     "./context": {
+      "@classytic/source": "./src/composition/context.ts",
       "types": "./dist/context.d.mts",
       "default": "./dist/context.mjs"
     },
     "./environment": {
+      "@classytic/source": "./src/composition/environment.ts",
       "types": "./dist/environment.d.mts",
       "default": "./dist/environment.mjs"
     },
     "./events": {
+      "@classytic/source": "./src/events/events.ts",
       "types": "./dist/events.d.mts",
       "default": "./dist/events.mjs"
     },
     "./memory-outbox": {
+      "@classytic/source": "./src/events/memory-outbox.ts",
       "types": "./dist/memory-outbox.d.mts",
       "default": "./dist/memory-outbox.mjs"
     },
     "./event-infra": {
+      "@classytic/source": "./src/events/event-infra.ts",
       "types": "./dist/event-infra.d.mts",
       "default": "./dist/event-infra.mjs"
     },
     "./outbox": {
+      "@classytic/source": "./src/events/outbox.ts",
       "types": "./dist/outbox.d.mts",
       "default": "./dist/outbox.mjs"
     },
     "./result": {
+      "@classytic/source": "./src/composition/result.ts",
       "types": "./dist/result.d.mts",
       "default": "./dist/result.mjs"
     },
     "./brand": {
+      "@classytic/source": "./src/composition/brand.ts",
       "types": "./dist/brand.d.mts",
       "default": "./dist/brand.mjs"
     },
     "./split-allocation": {
+      "@classytic/source": "./src/money/split-allocation.ts",
       "types": "./dist/split-allocation.d.mts",
       "default": "./dist/split-allocation.mjs"
     },
     "./approval": {
+      "@classytic/source": "./src/workflow/approval.ts",
       "types": "./dist/approval.d.mts",
       "default": "./dist/approval.mjs"
     },
     "./idempotency": {
+      "@classytic/source": "./src/workflow/idempotency.ts",
       "types": "./dist/idempotency.d.mts",
       "default": "./dist/idempotency.mjs"
     },
     "./cadence": {
+      "@classytic/source": "./src/scheduling/cadence.ts",
       "types": "./dist/cadence.d.mts",
       "default": "./dist/cadence.mjs"
     },
     "./hold": {
+      "@classytic/source": "./src/workflow/hold.ts",
       "types": "./dist/hold.d.mts",
       "default": "./dist/hold.mjs"
     },
     "./sla": {
+      "@classytic/source": "./src/scheduling/sla.ts",
       "types": "./dist/sla.d.mts",
       "default": "./dist/sla.mjs"
     },
     "./shelf-life": {
+      "@classytic/source": "./src/scheduling/shelf-life.ts",
       "types": "./dist/shelf-life.d.mts",
       "default": "./dist/shelf-life.mjs"
     },
     "./person": {
+      "@classytic/source": "./src/identity/person.ts",
       "types": "./dist/person.d.mts",
       "default": "./dist/person.mjs"
     },
     "./person-parse": {
+      "@classytic/source": "./src/identity/person-parse.ts",
       "types": "./dist/person-parse.d.mts",
       "default": "./dist/person-parse.mjs"
     },
     "./identity-verification": {
+      "@classytic/source": "./src/identity/identity-verification.ts",
       "types": "./dist/identity-verification.d.mts",
       "default": "./dist/identity-verification.mjs"
     },
     "./otp": {
+      "@classytic/source": "./src/identity/otp.ts",
       "types": "./dist/otp.d.mts",
       "default": "./dist/otp.mjs"
     },
     "./state-machine": {
+      "@classytic/source": "./src/workflow/state-machine.ts",
       "types": "./dist/state-machine.d.mts",
       "default": "./dist/state-machine.mjs"
     },
     "./bank-transaction": {
+      "@classytic/source": "./src/money/bank-transaction.ts",
       "types": "./dist/bank-transaction.d.mts",
       "default": "./dist/bank-transaction.mjs"
     },
     "./payment-gateway": {
+      "@classytic/source": "./src/money/payment-gateway.ts",
       "types": "./dist/payment-gateway.d.mts",
       "default": "./dist/payment-gateway.mjs"
     },
     "./payment-method-kind": {
+      "@classytic/source": "./src/money/payment-method-kind.ts",
       "types": "./dist/payment-method-kind.d.mts",
       "default": "./dist/payment-method-kind.mjs"
     },
     "./payment-allocation-status": {
+      "@classytic/source": "./src/money/payment-allocation-status.ts",
       "types": "./dist/payment-allocation-status.d.mts",
       "default": "./dist/payment-allocation-status.mjs"
     },
     "./monetization": {
+      "@classytic/source": "./src/money/monetization.ts",
       "types": "./dist/monetization.d.mts",
       "default": "./dist/monetization.mjs"
     },
     "./proration": {
+      "@classytic/source": "./src/money/proration.ts",
       "types": "./dist/proration.d.mts",
       "default": "./dist/proration.mjs"
     },
     "./payment-events": {
+      "@classytic/source": "./src/events/payment-events.ts",
       "types": "./dist/payment-events.d.mts",
       "default": "./dist/payment-events.mjs"
     },
     "./phone": {
+      "@classytic/source": "./src/identity/phone.ts",
       "types": "./dist/phone.d.mts",
       "default": "./dist/phone.mjs"
     },
     "./status-history": {
+      "@classytic/source": "./src/workflow/status-history.ts",
       "types": "./dist/status-history.d.mts",
       "default": "./dist/status-history.mjs"
     },
     "./condition": {
+      "@classytic/source": "./src/workflow/condition.ts",
       "types": "./dist/condition.d.mts",
       "default": "./dist/condition.mjs"
     },
     "./mixin": {
+      "@classytic/source": "./src/composition/mixin.ts",
       "types": "./dist/mixin.d.mts",
       "default": "./dist/mixin.mjs"
     },
     "./deadline": {
+      "@classytic/source": "./src/composition/deadline.ts",
       "types": "./dist/deadline.d.mts",
       "default": "./dist/deadline.mjs"
     },
     "./sla-policy": {
+      "@classytic/source": "./src/scheduling/sla-policy.ts",
       "types": "./dist/sla-policy.d.mts",
       "default": "./dist/sla-policy.mjs"
     },
     "./retention": {
+      "@classytic/source": "./src/retention/purge-evidence.ts",
       "types": "./dist/retention.d.mts",
       "default": "./dist/retention.mjs"
     },
     "./canonical": {
+      "@classytic/source": "./src/serialization/canonical.ts",
       "types": "./dist/canonical.d.mts",
       "default": "./dist/canonical.mjs"
     },
     "./csv": {
+      "@classytic/source": "./src/serialization/csv.ts",
       "types": "./dist/csv.d.mts",
       "default": "./dist/csv.mjs"
     },
     "./package.json": "./package.json",
     "./state-diagram": {
+      "@classytic/source": "./src/workflow/state-diagram.ts",
       "types": "./dist/state-diagram.d.mts",
       "default": "./dist/state-diagram.mjs"
     },
     "./suspension": {
+      "@classytic/source": "./src/workflow/suspension.ts",
       "types": "./dist/suspension.d.mts",
       "default": "./dist/suspension.mjs"
     },
+    "./legal-form": {
+      "@classytic/source": "./src/identity/legal-form.ts",
+      "types": "./dist/legal-form.d.mts",
+      "default": "./dist/legal-form.mjs"
+    },
     "./subject": {
+      "@classytic/source": "./src/identity/subject.ts",
       "types": "./dist/subject.d.mts",
       "default": "./dist/subject.mjs"
     },
     "./item-identity": {
+      "@classytic/source": "./src/identity/item-identity.ts",
       "types": "./dist/item-identity.d.mts",
       "default": "./dist/item-identity.mjs"
     },
     "./stock-level": {
+      "@classytic/source": "./src/inventory/stock-level.ts",
       "types": "./dist/stock-level.d.mts",
       "default": "./dist/stock-level.mjs"
     },
+    "./signed-token": {
+      "@classytic/source": "./src/security/signed-token.ts",
+      "types": "./dist/signed-token.d.mts",
+      "default": "./dist/signed-token.mjs"
+    },
+    "./item-stock": {
+      "@classytic/source": "./src/inventory/item-stock.ts",
+      "types": "./dist/item-stock.d.mts",
+      "default": "./dist/item-stock.mjs"
+    },
     "./item-facts": {
+      "@classytic/source": "./src/inventory/item-facts.ts",
       "types": "./dist/item-facts.d.mts",
       "default": "./dist/item-facts.mjs"
     },
+    "./line-settlement": {
+      "@classytic/source": "./src/inventory/line-settlement.ts",
+      "types": "./dist/line-settlement.d.mts",
+      "default": "./dist/line-settlement.mjs"
+    },
     "./testing/stock-key-seam": {
+      "@classytic/source": "./src/testing/stock-key-seam.ts",
       "types": "./dist/testing/stock-key-seam.d.mts",
       "default": "./dist/testing/stock-key-seam.mjs"
     }