@classytic/primitives 0.28.0 → 0.29.0

package/dist/legal-form.mjs

@@ -0,0 +1,27 @@
+//#region src/identity/legal-form.ts
+/**
+* The legal form of a person or entity — what the law treats it as, for the reporting company and its
+* counterparties alike. A sole proprietorship is an `individual`: the business has no legal personality
+* of its own. Country packs decide what follows from a form (equity accounts, the year-end close, tax).
+*/
+const LEGAL_FORMS = [
+	"individual",
+	"partnership",
+	"company",
+	"cooperative",
+	"nonprofit",
+	"government"
+];
+const LEGAL_FORM_LABELS = {
+	individual: "Individual / sole proprietorship",
+	partnership: "Partnership firm",
+	company: "Company",
+	cooperative: "Cooperative society",
+	nonprofit: "Nonprofit / NGO / trust",
+	government: "Government body"
+};
+function isLegalForm(value) {
+	return typeof value === "string" && LEGAL_FORMS.includes(value);
+}
+//#endregion
+export { LEGAL_FORMS, LEGAL_FORM_LABELS, isLegalForm };

package/dist/line-settlement.d.mts

@@ -0,0 +1,70 @@
+import { Result } from "./result.mjs";
+//#region src/inventory/line-settlement.d.ts
+/**
+ * A document line's quantity, split into OUTCOME buckets — the one definition
+ * of "how much of this line is still open".
+ *
+ * Every kernel that moves goods against a document asks this: an order line is
+ * fulfilled / returned / canceled, a transfer line is received / returned /
+ * written off, a purchase line is received / rejected. The buckets are the
+ * kernel's vocabulary; the arithmetic, the over-settlement guard and the state
+ * derivation are this file's, so no two kernels can answer differently.
+ *
+ * Quantities are whole units. A bucket that is absent counts as zero.
+ */
+interface SettlementLine<B extends string> {
+  /** What the line promised to move. */
+  readonly quantity: number;
+  /** What has been settled so far, per outcome. */
+  readonly settled: Readonly<Partial<Record<B, number>>>;
+}
+type SettlementState = "open" | "partial" | "settled";
+/** Sum of every bucket. */
+declare const settledTotal: <B extends string>(line: SettlementLine<B>) => number;
+/**
+ * `quantity − Σ buckets`. NOT clamped at zero: a negative means the line was
+ * over-settled by data written outside {@link planSettlement}, and hiding it
+ * would erase the only signal that happened.
+ */
+declare const outstandingOf: <B extends string>(line: SettlementLine<B>) => number;
+/** `open` — nothing settled; `settled` — nothing outstanding; otherwise `partial`. */
+declare const settlementState: <B extends string>(line: SettlementLine<B>) => SettlementState;
+/** Every line settled ⇒ `settled`; every line untouched ⇒ `open`; else `partial`. */
+declare const documentSettlementState: <B extends string>(lines: ReadonlyArray<SettlementLine<B>>) => SettlementState;
+/** `true` when every line is settled entirely through `bucket` (e.g. all received, nothing lost). */
+declare const settledEntirelyIn: <B extends string>(lines: ReadonlyArray<SettlementLine<B>>, bucket: B) => boolean;
+type SettlementRefusal = {
+  readonly code: "not_positive_integer";
+  readonly requested: number;
+} | {
+  readonly code: "exceeds_outstanding";
+  readonly requested: number;
+  readonly outstanding: number;
+};
+/**
+ * Settle `quantity` more units into `bucket`, or refuse.
+ *
+ * Refuses a non-positive or fractional quantity and anything above what is
+ * outstanding — an over-settlement is an input error, never silently trimmed.
+ * Use {@link clampSettlement} only where the surface's CONTRACT is "take what fits".
+ */
+declare const planSettlement: <B extends string>(line: SettlementLine<B>, bucket: B, quantity: number) => Result<SettlementLine<B>, SettlementRefusal>;
+/**
+ * Settle up to `requested` units into `bucket`, taking only what is outstanding.
+ * `applied` is what was actually settled; `0` leaves the line unchanged.
+ */
+declare const clampSettlement: <B extends string>(line: SettlementLine<B>, bucket: B, requested: number) => {
+  readonly line: SettlementLine<B>;
+  readonly applied: number;
+};
+/**
+ * The share of a line-level amount (a value or a cost, integer MINOR units) owed by one
+ * settlement batch, given how many units the whole line had settled before and after it.
+ *
+ * `floor(total·after/q) − floor(total·before/q)` TELESCOPES: however a line is split into
+ * batches, and across every outcome bucket, the shares sum to exactly `total` once the line
+ * is fully settled — no remainder to chase, no batch-order dependence.
+ */
+declare const shareOfSettled: (total: number, quantity: number, settledBefore: number, settledAfter: number) => number;
+//#endregion
+export { SettlementLine, SettlementRefusal, SettlementState, clampSettlement, documentSettlementState, outstandingOf, planSettlement, settledEntirelyIn, settledTotal, settlementState, shareOfSettled };

package/dist/line-settlement.mjs

@@ -0,0 +1,79 @@
+import { err, ok } from "./result.mjs";
+//#region src/inventory/line-settlement.ts
+/** Sum of every bucket. */
+const settledTotal = (line) => Object.values(line.settled).reduce((sum, n) => sum + (n ?? 0), 0);
+/**
+* `quantity − Σ buckets`. NOT clamped at zero: a negative means the line was
+* over-settled by data written outside {@link planSettlement}, and hiding it
+* would erase the only signal that happened.
+*/
+const outstandingOf = (line) => line.quantity - settledTotal(line);
+/** `open` — nothing settled; `settled` — nothing outstanding; otherwise `partial`. */
+const settlementState = (line) => {
+	if (outstandingOf(line) <= 0) return "settled";
+	return settledTotal(line) === 0 ? "open" : "partial";
+};
+/** Every line settled ⇒ `settled`; every line untouched ⇒ `open`; else `partial`. */
+const documentSettlementState = (lines) => {
+	const states = lines.map(settlementState);
+	if (states.every((s) => s === "settled")) return "settled";
+	if (states.every((s) => s === "open")) return "open";
+	return "partial";
+};
+/** `true` when every line is settled entirely through `bucket` (e.g. all received, nothing lost). */
+const settledEntirelyIn = (lines, bucket) => lines.every((l) => (l.settled[bucket] ?? 0) >= l.quantity);
+/**
+* Settle `quantity` more units into `bucket`, or refuse.
+*
+* Refuses a non-positive or fractional quantity and anything above what is
+* outstanding — an over-settlement is an input error, never silently trimmed.
+* Use {@link clampSettlement} only where the surface's CONTRACT is "take what fits".
+*/
+const planSettlement = (line, bucket, quantity) => {
+	if (!Number.isInteger(quantity) || quantity <= 0) return err({
+		code: "not_positive_integer",
+		requested: quantity
+	});
+	const outstanding = outstandingOf(line);
+	if (quantity > outstanding) return err({
+		code: "exceeds_outstanding",
+		requested: quantity,
+		outstanding
+	});
+	return ok(withBucket(line, bucket, quantity));
+};
+/**
+* Settle up to `requested` units into `bucket`, taking only what is outstanding.
+* `applied` is what was actually settled; `0` leaves the line unchanged.
+*/
+const clampSettlement = (line, bucket, requested) => {
+	const applied = Math.max(0, Math.min(Math.trunc(requested), outstandingOf(line)));
+	return {
+		line: applied > 0 ? withBucket(line, bucket, applied) : line,
+		applied
+	};
+};
+/**
+* The share of a line-level amount (a value or a cost, integer MINOR units) owed by one
+* settlement batch, given how many units the whole line had settled before and after it.
+*
+* `floor(total·after/q) − floor(total·before/q)` TELESCOPES: however a line is split into
+* batches, and across every outcome bucket, the shares sum to exactly `total` once the line
+* is fully settled — no remainder to chase, no batch-order dependence.
+*/
+const shareOfSettled = (total, quantity, settledBefore, settledAfter) => {
+	if (!Number.isInteger(total) || total < 0) throw new RangeError(`total must be a non-negative integer, got ${total}`);
+	if (!Number.isInteger(quantity) || quantity <= 0) throw new RangeError(`quantity must be a positive integer, got ${quantity}`);
+	if (!(0 <= settledBefore && settledBefore <= settledAfter && settledAfter <= quantity)) throw new RangeError(`need 0 <= before (${settledBefore}) <= after (${settledAfter}) <= quantity (${quantity})`);
+	const at = (n) => Number(BigInt(total) * BigInt(n) / BigInt(quantity));
+	return at(settledAfter) - at(settledBefore);
+};
+const withBucket = (line, bucket, quantity) => ({
+	quantity: line.quantity,
+	settled: {
+		...line.settled,
+		[bucket]: (line.settled[bucket] ?? 0) + quantity
+	}
+});
+//#endregion
+export { clampSettlement, documentSettlementState, outstandingOf, planSettlement, settledEntirelyIn, settledTotal, settlementState, shareOfSettled };

package/dist/memory-outbox.mjs

@@ -74,7 +74,8 @@ var MemoryOutboxStore = class {
 			entry.fenceToken = (entry.fenceToken ?? 0) + 1;
 			claimed.push({
 				event: entry.event,
-				fencingToken: entry.fenceToken
+				fencingToken: entry.fenceToken,
+				attempts: entry.attempts
 			});
 		}
 		return claimed;

package/dist/outbox.d.mts

@@ -46,6 +46,20 @@ interface OutboxClaimOptions {
 interface OutboxClaimedEvent {
   readonly event: DomainEvent;
   readonly fencingToken: number;
+  /**
+   * DURABLE delivery-attempt count for this event, INCLUDING the claim that
+   * returned it (1 on the first claim). Optional: stores that persist a
+   * per-row counter report it; stores that don't leave it absent.
+   *
+   * Why it exists: a relay can only count failures in its own memory, and
+   * that count is wrong in exactly the cases a failure policy exists for.
+   * A poison event that crashes the relay restarts at 1 on every boot, so
+   * `attempts >= 5 → deadLetter` never fires; and across N relays sharing a
+   * store, each counts its own attempts, so "5" means 5×N. The store already
+   * increments a counter atomically inside the claim — reporting it here is
+   * what lets the policy see the true number.
+   */
+  readonly attempts?: number;
 }
 /** Options for {@link OutboxStore.acknowledge}. */
 interface OutboxAcknowledgeOptions {
@@ -81,9 +95,12 @@ interface OutboxFailureContext {
   /** The error returned by the transport / handler. */
   readonly error: Error;
   /**
-   * Attempt count including this failure (1 on the first fail). Tracked
-   * in-process by the relay; accurate within a single relay process, resets
-   * on restart. For durable attempt counts, the policy can query the store.
+   * Attempt count including this failure (1 on the first fail).
+   *
+   * DURABLE when the store reports {@link OutboxClaimedEvent.attempts} from a
+   * fenced claim — survives relay restarts and is shared by every relay on the
+   * store. Otherwise the relay's in-process count: accurate within one relay
+   * process, reset on restart. Relays take the larger of the two.
    */
   readonly attempts: number;
 }

package/dist/payment-events.d.mts

@@ -119,6 +119,9 @@ interface PaymentRefundedPayload {
   refundId: string;
   providerRef?: string;
   providerCode: string;
+  /** How the original payment moved — money goes back the way it came, so this places the refund too. */
+  methodKind: PaymentMethodKind;
+  methodCode?: string;
   /** Amount refunded in this event — may be less than the original payment. */
   refundedAmount: Money;
   /** Original payment total — present so consumers can compute remaining refundable without a Payment lookup. */
@@ -142,6 +145,9 @@ interface PaymentReversedPayload {
   paymentId: string;
   providerRef?: string;
   providerCode: string;
+  /** How the payment being unwound moved. */
+  methodKind: PaymentMethodKind;
+  methodCode?: string;
   /** Amount being unwound — equals the original payment for full reversal, less for partial. */
   reversedAmount: Money;
   /** Original payment total — present so consumers can detect partial vs full without a Payment lookup. */

package/dist/period.d.mts

@@ -123,6 +123,27 @@ declare function resolveMonth(year: number, month: number, timezone: string): Da
 declare function resolveQuarter(year: number, quarter: 1 | 2 | 3 | 4, timezone: string): DateRange;
 /** Half-open `[start, end)` range covering one local calendar year. */
 declare function resolveYear(year: number, timezone: string): DateRange;
+/** A fiscal year: the calendar year it starts in, its label, and its half-open local range. */
+interface FiscalYear {
+  startYear: number;
+  /** `2026-27` for a year starting mid-calendar-year; `2026` for one starting in January. */
+  label: string;
+  range: DateRange;
+}
+/** Half-open range of the fiscal year starting on the 1st of `startMonth` of `startYear`, local to `timezone`. */
+declare function resolveFiscalYear(startYear: number, opts: {
+  startMonth: number;
+  timezone: string;
+}): DateRange;
+/**
+ * The fiscal year `date` falls in — 1 July–30 June (Bangladesh, Australia), 1 April–31 March (India),
+ * 1 January (most) — decided on the LOCAL calendar day in `timezone`, so the last evening of June in Dhaka
+ * is still the old year.
+ */
+declare function fiscalYearOf(date: Date, opts: {
+  startMonth: number;
+  timezone: string;
+}): FiscalYear;
 /**
  * Half-open range spanning two local dates, INCLUSIVE of both days — what an
  * operator means by "1st to 31st". The half-open end is therefore the start of
@@ -209,4 +230,4 @@ declare function parsePeriod(label: string, timezone?: string): Period;
  */
 declare function formatPeriod(period: Period): string;
 //#endregion
-export { DateRange, DateRangeError, Period, PeriodError, PeriodErrorCode, PeriodGranularity, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };
+export { DateRange, DateRangeError, FiscalYear, Period, PeriodError, PeriodErrorCode, PeriodGranularity, dayStart, fiscalYearOf, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveFiscalYear, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };

package/dist/period.mjs

@@ -181,6 +181,35 @@ function resolveYear(year, timezone) {
 		end: dayStart(`${y + 1}-01-01`, zone)
 	};
 }
+/** Half-open range of the fiscal year starting on the 1st of `startMonth` of `startYear`, local to `timezone`. */
+function resolveFiscalYear(startYear, opts) {
+	const zone = assertZone(opts.timezone);
+	const y = assertYear(startYear);
+	const m = assertMonth(opts.startMonth);
+	return {
+		start: dayStart(`${y}-${pad2(m)}-01`, zone),
+		end: dayStart(`${y + 1}-${pad2(m)}-01`, zone)
+	};
+}
+/**
+* The fiscal year `date` falls in — 1 July–30 June (Bangladesh, Australia), 1 April–31 March (India),
+* 1 January (most) — decided on the LOCAL calendar day in `timezone`, so the last evening of June in Dhaka
+* is still the old year.
+*/
+function fiscalYearOf(date, opts) {
+	const zone = assertZone(opts.timezone);
+	const m = assertMonth(opts.startMonth);
+	const [y, mm] = String(civilDateOf(date, zone)).split("-").map(Number);
+	const startYear = mm >= m ? y : y - 1;
+	return {
+		startYear,
+		label: m === 1 ? String(startYear) : `${startYear}-${pad2((startYear + 1) % 100)}`,
+		range: resolveFiscalYear(startYear, {
+			startMonth: m,
+			timezone: zone
+		})
+	};
+}
 /**
 * Half-open range spanning two local dates, INCLUSIVE of both days — what an
 * operator means by "1st to 31st". The half-open end is therefore the start of
@@ -388,4 +417,4 @@ function formatPeriod(period) {
 	throw new PeriodError("INVALID_LABEL", "An ad-hoc Period (start + end) has no canonical label.");
 }
 //#endregion
-export { DateRangeError, PeriodError, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };
+export { DateRangeError, PeriodError, dayStart, fiscalYearOf, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveFiscalYear, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };

package/dist/phone.d.mts

@@ -40,7 +40,19 @@ declare function formatPhone(phone: PhoneNumber): string;
  * @example formatNational(parsePhone('+14155550182').value!) → '+1 415 555 0182'
  */
 declare function formatNational(phone: PhoneNumber): string;
+/**
+ * Prefix of a stored PLACEHOLDER phone: a record whose `phone` is required and
+ * unique but was created before a number was known gets `pending_<id>`. It means
+ * "no number collected" — never a number to show, dial, dedupe or search on.
+ */
+declare const PLACEHOLDER_PHONE_PREFIX = "pending_";
+/** Mint the placeholder for a phone-less record — unique per `id`. */
+declare function placeholderPhone(id: string): string;
+/** True for a stored placeholder (see {@link PLACEHOLDER_PHONE_PREFIX}); whitespace-tolerant. */
+declare function isPlaceholderPhone(value: unknown): boolean;
+/** A stored phone worth showing: trimmed, or `null` for empty or a placeholder. */
+declare function shownPhone(value: unknown): string | null;
 /** Type guard. */
 declare function isPhoneNumber(value: unknown): value is PhoneNumber;
 //#endregion
-export { PhoneError, PhoneErrorCode, PhoneNumber, formatNational, formatPhone, isPhoneNumber, parsePhone };
+export { PLACEHOLDER_PHONE_PREFIX, PhoneError, PhoneErrorCode, PhoneNumber, formatNational, formatPhone, isPhoneNumber, isPlaceholderPhone, parsePhone, placeholderPhone, shownPhone };

package/dist/phone.mjs

@@ -302,9 +302,29 @@ function formatNational(phone) {
 	const groups = phone.nationalNumber.match(/.{1,3}/g) ?? [];
 	return `+${phone.callingCode} ${groups.join(" ")}`.trim();
 }
+/**
+* Prefix of a stored PLACEHOLDER phone: a record whose `phone` is required and
+* unique but was created before a number was known gets `pending_<id>`. It means
+* "no number collected" — never a number to show, dial, dedupe or search on.
+*/
+const PLACEHOLDER_PHONE_PREFIX = "pending_";
+/** Mint the placeholder for a phone-less record — unique per `id`. */
+function placeholderPhone(id) {
+	return `${PLACEHOLDER_PHONE_PREFIX}${id}`;
+}
+/** True for a stored placeholder (see {@link PLACEHOLDER_PHONE_PREFIX}); whitespace-tolerant. */
+function isPlaceholderPhone(value) {
+	return typeof value === "string" && value.trim().startsWith("pending_");
+}
+/** A stored phone worth showing: trimmed, or `null` for empty or a placeholder. */
+function shownPhone(value) {
+	if (typeof value !== "string") return null;
+	const v = value.trim();
+	return v && !isPlaceholderPhone(v) ? v : null;
+}
 /** Type guard. */
 function isPhoneNumber(value) {
 	return typeof value === "object" && value !== null && typeof value.e164 === "string" && typeof value.callingCode === "string" && typeof value.nationalNumber === "string" && value.e164.startsWith("+");
 }
 //#endregion
-export { PhoneError, formatNational, formatPhone, isPhoneNumber, parsePhone };
+export { PLACEHOLDER_PHONE_PREFIX, PhoneError, formatNational, formatPhone, isPhoneNumber, isPlaceholderPhone, parsePhone, placeholderPhone, shownPhone };

package/dist/proration.d.mts

@@ -62,6 +62,16 @@ declare function splitByPeriodFraction(amount: Money, fraction: PeriodFraction):
   readonly consumed: Money;
   readonly remaining: Money;
 };
+/**
+ * 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.
+ */
+declare function apportion(total: number, part: number, whole: number): number;
 /**
  * Allocate the `fraction`-weighted part of a `Money` amount, drift-free — the
  * complement (`1 - fraction`) is discarded but computed so rounding is exact
@@ -72,4 +82,4 @@ declare function splitByPeriodFraction(amount: Money, fraction: PeriodFraction):
  */
 declare function allocateMoneyByFraction(amount: Money, fraction: number): Money;
 //#endregion
-export { PeriodFraction, PeriodProgressInput, ProrationError, ProrationErrorCode, ProrationGranularity, allocateMoneyByFraction, periodProgress, splitByPeriodFraction };
+export { PeriodFraction, PeriodProgressInput, ProrationError, ProrationErrorCode, ProrationGranularity, allocateMoneyByFraction, apportion, periodProgress, splitByPeriodFraction };

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 };