@cotal-ai/core 0.26.0 → 0.28.0-hack-20260823202734

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export * from "./session-terminal-frames.js";
 export * from "./endpoint-virtual.js";
 export * from "./endpoint-receipt.js";
 export * from "./endpoint-signing.js";
+export * from "./signing-key-rotation.js";
 export * from "./endpoint-traits.js";
 export * from "./safe-pattern.js";
 export * from "./resolve.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -29,6 +29,7 @@ export * from "./session-terminal-frames.js";
 export * from "./endpoint-virtual.js";
 export * from "./endpoint-receipt.js";
 export * from "./endpoint-signing.js";
+export * from "./signing-key-rotation.js";
 export * from "./endpoint-traits.js";
 export * from "./safe-pattern.js";
 export * from "./resolve.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}

package/dist/signing-key-rotation.d.ts

@@ -0,0 +1,85 @@
+/**
+ * A signing key that outlives its own validity window.
+ *
+ * A signer minted at boot with `validTo: Date.now() + TTL` is correct for exactly TTL and then
+ * permanently broken. Nothing re-mints it, so a process that stays up past its window loses the
+ * plane that key serves - and no restart of the CLIENT helps, because the expiry is in the SERVER's
+ * frozen anchor. Observed three times in one day on a manager whose session key was minted at boot
+ * with a flat 24h window: at +34.5h every attach failed closed with "outside its validity window",
+ * and the only recovery anyone found was restarting the manager, which killed every live session.
+ *
+ * Failing closed on an expired key is correct (SPEC 13.10) and is not what this changes. What this
+ * changes is that the key stops expiring unattended: it is renewed well before the edge, and the
+ * previous key stays verifiable for an overlap so artifacts signed a moment before the swap do not
+ * become unverifiable a moment after it.
+ *
+ * The rule follows the auth issuer, which has had it all along: sign with the newest key, verify
+ * against any live key, drop a key only once nothing it signed can still be in flight.
+ */
+import type { AnchorRole, SignerAnchor } from "./endpoint-signing.js";
+/** Renew once this fraction of the window has elapsed. A third leaves two thirds of the window as
+ *  margin, so a renewal can fail and be retried many times before anything expires. */
+export declare const RENEW_AT_FRACTION: number;
+/** How long a replaced key stays verifiable. It must exceed the longest artifact TTL that key can
+ *  sign, or a grant issued just before the swap outlives the ability to verify it. */
+export declare const OVERLAP_MS: number;
+/** A key that can sign, paired with the anchor a verifier resolves for it. */
+export interface KeyGeneration {
+    keyId: string;
+    keyPair: {
+        sign(input: Uint8Array): Uint8Array;
+    };
+    anchor: SignerAnchor;
+}
+/** Mint a fresh generation. Supplied by the caller so this module never owns key material. */
+export type MintGeneration = (seq: number, now: number) => KeyGeneration;
+/**
+ * When the current generation should be replaced.
+ *
+ * Deliberately a fraction of the window rather than a fixed lead time: a short-lived key and a
+ * long-lived one both get proportional margin, and a caller cannot accidentally configure a lead
+ * time longer than the window itself (which would renew on every single check).
+ */
+export declare function renewalDueAt(anchor: Pick<SignerAnchor, "validFrom" | "validTo">): number;
+/** Whether `now` has reached the renewal point for this anchor. */
+export declare function needsRenewal(anchor: Pick<SignerAnchor, "validFrom" | "validTo">, now: number): boolean;
+/**
+ * A rotating signing key: always signs with the newest generation, resolves any generation still
+ * inside its overlap, and drops the rest.
+ *
+ * The renewal is driven by {@link maybeRenew}, which the owner calls on a timer AND opportunistically
+ * before signing. Both matter: a timer alone stops if the event loop is starved or the process is
+ * suspended, and an opportunistic check alone never fires on an idle plane that then has to sign
+ * after a long quiet period. Together, an expired key requires both a dead timer and no signing.
+ */
+export declare class RotatingSigner {
+    #private;
+    constructor(mint: MintGeneration, now: number);
+    /** The generation to sign with: always the newest. */
+    current(): KeyGeneration;
+    /** Resolve an anchor by keyId across every generation still retained. A verifier must be able to
+     *  check an artifact signed just before a swap, which is the entire point of the overlap. */
+    resolve(keyId: string): SignerAnchor | undefined;
+    /** Every generation currently retained, newest last. Observability for the owner's logs. */
+    generations(): readonly KeyGeneration[];
+    /**
+     * Renew if the current generation has reached its renewal point, then drop generations whose
+     * overlap has passed. Idempotent and cheap: safe to call before every signature.
+     *
+     * Returns the new keyId when a rotation happened, so the owner can log a fact rather than a hope.
+     */
+    maybeRenew(now: number): string | undefined;
+}
+/** Build the anchor for a generation. Kept here so every caller gets the same window shape. */
+export declare function generationAnchor(args: {
+    keyId: string;
+    publicKey: string;
+    owner: string;
+    roles: readonly AnchorRole[];
+    scope: SignerAnchor["scope"];
+    now: number;
+    ttlMs: number;
+    /** Tolerance for a verifier whose clock runs slightly behind this signer's. */
+    skewMs?: number;
+}): SignerAnchor;
+//# sourceMappingURL=signing-key-rotation.d.ts.map

package/dist/signing-key-rotation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing-key-rotation.d.ts","sourceRoot":"","sources":["../src/signing-key-rotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAEtE;uFACuF;AACvF,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AACvC;sFACsF;AACtF,eAAO,MAAM,UAAU,QAAiB,CAAC;AAEzC,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE;QAAE,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAA;KAAE,CAAC;IACjD,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,8FAA8F;AAC9F,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,aAAa,CAAC;AAEzE;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,GAAG,SAAS,CAAC,GAAG,MAAM,CAGxF;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,GAAG,SAAS,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEtG;AAED;;;;;;;;GAQG;AACH,qBAAa,cAAc;;gBAKb,IAAI,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM;IAK7C,sDAAsD;IACtD,OAAO,IAAI,aAAa;IAIxB;iGAC6F;IAC7F,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIhD,4FAA4F;IAC5F,WAAW,IAAI,SAAS,aAAa,EAAE;IAIvC;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAa5C;AAED,+FAA+F;AAC/F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7B,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,YAAY,CAWf"}

package/dist/signing-key-rotation.js

@@ -0,0 +1,85 @@
+/** Renew once this fraction of the window has elapsed. A third leaves two thirds of the window as
+ *  margin, so a renewal can fail and be retried many times before anything expires. */
+export const RENEW_AT_FRACTION = 1 / 3;
+/** How long a replaced key stays verifiable. It must exceed the longest artifact TTL that key can
+ *  sign, or a grant issued just before the swap outlives the ability to verify it. */
+export const OVERLAP_MS = 10 * 60 * 1000;
+/**
+ * When the current generation should be replaced.
+ *
+ * Deliberately a fraction of the window rather than a fixed lead time: a short-lived key and a
+ * long-lived one both get proportional margin, and a caller cannot accidentally configure a lead
+ * time longer than the window itself (which would renew on every single check).
+ */
+export function renewalDueAt(anchor) {
+    const span = anchor.validTo - anchor.validFrom;
+    return anchor.validFrom + Math.floor(span * RENEW_AT_FRACTION);
+}
+/** Whether `now` has reached the renewal point for this anchor. */
+export function needsRenewal(anchor, now) {
+    return now >= renewalDueAt(anchor);
+}
+/**
+ * A rotating signing key: always signs with the newest generation, resolves any generation still
+ * inside its overlap, and drops the rest.
+ *
+ * The renewal is driven by {@link maybeRenew}, which the owner calls on a timer AND opportunistically
+ * before signing. Both matter: a timer alone stops if the event loop is starved or the process is
+ * suspended, and an opportunistic check alone never fires on an idle plane that then has to sign
+ * after a long quiet period. Together, an expired key requires both a dead timer and no signing.
+ */
+export class RotatingSigner {
+    #generations = [];
+    #seq = 0;
+    #mint;
+    constructor(mint, now) {
+        this.#mint = mint;
+        this.#generations.push(this.#mint(this.#seq++, now));
+    }
+    /** The generation to sign with: always the newest. */
+    current() {
+        return this.#generations[this.#generations.length - 1];
+    }
+    /** Resolve an anchor by keyId across every generation still retained. A verifier must be able to
+     *  check an artifact signed just before a swap, which is the entire point of the overlap. */
+    resolve(keyId) {
+        return this.#generations.find((g) => g.keyId === keyId)?.anchor;
+    }
+    /** Every generation currently retained, newest last. Observability for the owner's logs. */
+    generations() {
+        return this.#generations;
+    }
+    /**
+     * Renew if the current generation has reached its renewal point, then drop generations whose
+     * overlap has passed. Idempotent and cheap: safe to call before every signature.
+     *
+     * Returns the new keyId when a rotation happened, so the owner can log a fact rather than a hope.
+     */
+    maybeRenew(now) {
+        let rotated;
+        if (needsRenewal(this.current().anchor, now)) {
+            const next = this.#mint(this.#seq++, now);
+            this.#generations.push(next);
+            rotated = next.keyId;
+        }
+        // Never drop the newest, whatever the clock says: a plane with no signer cannot serve at all,
+        // and a key that is somehow already past its overlap is still better than nothing to sign with.
+        const newest = this.#generations[this.#generations.length - 1];
+        this.#generations = this.#generations.filter((g) => g === newest || now <= g.anchor.validTo + OVERLAP_MS);
+        return rotated;
+    }
+}
+/** Build the anchor for a generation. Kept here so every caller gets the same window shape. */
+export function generationAnchor(args) {
+    const skew = args.skewMs ?? 60_000;
+    return {
+        keyId: args.keyId,
+        publicKey: args.publicKey,
+        owner: args.owner,
+        roles: args.roles,
+        scope: args.scope,
+        validFrom: args.now - skew,
+        validTo: args.now + args.ttlMs,
+    };
+}
+//# sourceMappingURL=signing-key-rotation.js.map

package/dist/signing-key-rotation.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cotal-ai/core",
   "description": "The Cotal protocol: endpoint, subjects, message types, the NATS client layer, and the extension contracts.",
-  "version": "0.26.0",
+  "version": "0.28.0-hack-20260823202734",
   "license": "Apache-2.0",
   "keywords": [
     "cotal",
@@ -45,6 +45,7 @@
     "@nats-io/jwt": "0.0.10-5",
     "@nats-io/kv": "^3.4.0",
     "@nats-io/obj": "^3.4.0",
+    "@nats-io/nats-core": "^3.4.0",
     "@nats-io/nkeys": "^2.0.3",
     "@nats-io/transport-node": "^3.4.0",
     "ajv": "^8.20.0",