feat!: enforce mandatory token expiration with capped lifetimes

Changes:
- Add time constants (ONE_MINUTE_MS, ONE_HOUR_MS, FOUR_WEEKS_MS, DEFAULT_MAX_LIFETIME_MS)
- Add `expiresIn()` method to builder for ergonomic expiration setting
- Add `maxLifetime()` method to customize maximum token lifetime
- Add validation in `sign()` to require expiration and enforce lifetime caps
- Fix time unit bug: convert milliseconds to seconds in payload (exp, nbf)
- Cap chained token lifetimes by parent's remaining validity
- Update NilauthClient to set expiration on internal tokens
- Update documentation and all tests to use new expiration API

Security improvements:
- Prevents tokens from being created without expiration dates
- Enforces maximum lifetime of 4 weeks by default
- Child tokens cannot outlive their parents
- Provides clear error messages when lifetime constraints are violated

BREAKING CHANGE: All tokens must now specify an expiration via `expiresAt()` or `expiresIn()`. Tokens without expiration will be rejected during the build process.

Author: tim-hm

DOCUMENTATION.md

@@ -56,7 +56,7 @@ const rootDelegation = await Builder.delegation()
     ["==", ".command", "/nil/db/collections"], // Command must be an attenuation
     ["!=", ".args.collection", "secrets"]
   ])
-  .expiresAt(Date.now() + 3600 * 1000)    // Expires in 1 hour
+  .expiresIn(3600 * 1000)                 // Expires in 1 hour
   .sign(rootSigner);
 
 // Step 4: Build an invocation token from the delegation

biome.jsonc

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.2.4/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.2.6/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",

src/constants.ts

@@ -1 +1,6 @@
+export const ONE_MINUTE_MS = 60 * 1000;
+export const ONE_HOUR_MS = 60 * ONE_MINUTE_MS;
+export const FOUR_WEEKS_MS = 4 * 7 * 24 * ONE_HOUR_MS;
+export const DEFAULT_LIFETIME_MS = ONE_HOUR_MS;
+export const DEFAULT_MAX_LIFETIME_MS = FOUR_WEEKS_MS;
 export const DEFAULT_NONCE_LENGTH = 16;

src/nuc/builder.ts

@@ -1,5 +1,5 @@
 import { bytesToHex, randomBytes } from "@noble/hashes/utils.js";
-import { DEFAULT_NONCE_LENGTH } from "#/constants";
+import { DEFAULT_MAX_LIFETIME_MS, DEFAULT_NONCE_LENGTH } from "#/constants";
 import type { Did } from "#/core/did/types";
 import { base64UrlEncode } from "#/core/encoding";
 import type { Signer } from "#/core/signer";
@@ -23,6 +23,7 @@ abstract class AbstractBuilder {
   protected _meta?: Record<string, unknown>;
   protected _nonce?: string;
   protected _proof?: Envelope;
+  protected _maxLifetimeMs: number = DEFAULT_MAX_LIFETIME_MS;
 
   protected abstract _getPayloadData(issuer: Did): Payload;
 
@@ -83,6 +84,21 @@ abstract class AbstractBuilder {
     return this;
   }
 
+  /**
+   * Specifies the token's expiration as a duration from now.
+   *
+   * @param ms - The number of milliseconds from now when the token should expire.
+   * @returns This builder instance for method chaining.
+   * @example
+   * ```typescript
+   * builder.expiresIn(3600 * 1000); // Expires in 1 hour
+   * ```
+   */
+  public expiresIn(ms: number): this {
+    this._expiresAt = Date.now() + ms;
+    return this;
+  }
+
   /**
    * Specifies the earliest time the token becomes valid.
    *
@@ -141,6 +157,26 @@ abstract class AbstractBuilder {
     return this;
   }
 
+  /**
+   * Sets the maximum lifetime for the token being built.
+   *
+   * This value cannot exceed the default maximum lifetime or the remaining
+   * lifetime of a parent proof token.
+   *
+   * @param ms - The maximum lifetime in milliseconds.
+   * @returns This builder instance for method chaining.
+   * @throws {Error} If the provided lifetime exceeds the allowed maximum.
+   */
+  public maxLifetime(ms: number): this {
+    if (ms > this._maxLifetimeMs) {
+      throw new Error(
+        `Custom max lifetime of ${ms}ms exceeds the allowed maximum of ${this._maxLifetimeMs}ms.`,
+      );
+    }
+    this._maxLifetimeMs = ms;
+    return this;
+  }
+
   /**
    * Links this token to a previous token in a delegation chain.
    *
@@ -197,6 +233,24 @@ abstract class AbstractBuilder {
    * ```
    */
   public async sign(signer: Signer): Promise<Envelope> {
+    // Validate expiration properties before signing.
+    if (!this._expiresAt) {
+      throw new Error(
+        "Expiration is a required field. Use `expiresAt(timestamp)` or `expiresIn(duration)`.",
+      );
+    }
+    if (this._expiresAt <= Date.now()) {
+      throw new Error("Expiration date must be in the future.");
+    }
+    const maxExpiry = Date.now() + this._maxLifetimeMs;
+    if (this._expiresAt > maxExpiry) {
+      const asConfigured = new Date(this._expiresAt).toISOString();
+      const maxAllowed = new Date(maxExpiry).toISOString();
+      throw new Error(
+        `Expiration of ${asConfigured} exceeds the maximum lifetime. Max expiry is ${maxAllowed}.`,
+      );
+    }
+
     // The issuer is now authoritatively derived from the signer.
     const issuer = this._issuer ?? (await signer.getDid());
     const payloadData = this._getPayloadData(issuer);
@@ -330,8 +384,8 @@ export class DelegationBuilder extends AbstractBuilder {
       sub: this._subject,
       cmd: this._command,
       pol: this._policy,
-      nbf: this._notBefore,
-      exp: this._expiresAt,
+      nbf: this._notBefore ? Math.floor(this._notBefore / 1000) : undefined,
+      exp: this._expiresAt ? Math.floor(this._expiresAt / 1000) : undefined,
       meta: this._meta,
       nonce: this._nonce || bytesToHex(randomBytes(DEFAULT_NONCE_LENGTH)),
       prf: this._proof
@@ -415,8 +469,8 @@ export class InvocationBuilder extends AbstractBuilder {
       sub: this._subject,
       cmd: this._command,
       args: this._args,
-      nbf: this._notBefore,
-      exp: this._expiresAt,
+      nbf: this._notBefore ? Math.floor(this._notBefore / 1000) : undefined,
+      exp: this._expiresAt ? Math.floor(this._expiresAt / 1000) : undefined,
       meta: this._meta,
       nonce: this._nonce || bytesToHex(randomBytes(DEFAULT_NONCE_LENGTH)),
       prf: this._proof
@@ -536,6 +590,15 @@ export const Builder = {
     builder.command(proofPayload.cmd);
     builder.proof(proof);
 
+    // Cap the new token's lifetime by its parent's remaining validity.
+    if (proofPayload.exp) {
+      const remainingLifetimeMs = proofPayload.exp * 1000 - Date.now();
+      if (remainingLifetimeMs <= 0) {
+        throw new Error("Cannot create a chained token from an expired proof.");
+      }
+      builder.maxLifetime(remainingLifetimeMs);
+    }
+
     return builder;
   },
 
@@ -577,6 +640,15 @@ export const Builder = {
     builder.command(proofPayload.cmd);
     builder.proof(proof);
 
+    // Cap the new token's lifetime by its parent's remaining validity.
+    if (proofPayload.exp) {
+      const remainingLifetimeMs = proofPayload.exp * 1000 - Date.now();
+      if (remainingLifetimeMs <= 0) {
+        throw new Error("Cannot create a chained token from an expired proof.");
+      }
+      builder.maxLifetime(remainingLifetimeMs);
+    }
+
     return builder;
   },
 

src/services/nilauth/client.ts

@@ -2,6 +2,7 @@ import { sha256 } from "@noble/hashes/sha2.js";
 import { bytesToHex, randomBytes } from "@noble/hashes/utils.js";
 import ky, { HTTPError, type Options } from "ky";
 import { z } from "zod";
+import { ONE_MINUTE_MS } from "#/constants";
 import { Did } from "#/core/did/did";
 import {
   NilauthErrorResponse,
@@ -161,6 +162,7 @@ export class NilauthClient {
       .subject(subject)
       .audience(this.nilauthDid)
       .command(command)
+      .expiresIn(ONE_MINUTE_MS)
       .signAndSerialize(signer);
   }
 
@@ -415,14 +417,19 @@ export class NilauthClient {
 
     const issuer = await signer.getDid();
 
+    // Calculate auth token's remaining lifetime
+    const authTokenExp = authToken.nuc.payload.exp;
+    const remainingLifetimeMs = (authTokenExp as number) * 1000 - Date.now();
+
     const revokeTokenEnvelope = await Builder.invocationFrom(authToken)
       .arguments({
         token: Codec.serializeBase64Url(tokenToRevoke),
       })
       .command(REVOKE_COMMAND)
       .audience(this.nilauthDid)
       .issuer(issuer)
-      // Subject is inherited from authToken
+      // Use most of parent's remaining lifetime (builder will cap if needed)
+      .expiresIn(Math.min(ONE_MINUTE_MS, remainingLifetimeMs * 0.9))
       .sign(signer);
 
     const revokeTokenString = Codec.serializeBase64Url(revokeTokenEnvelope);

tests/integration/heterogeneous-chain.test.ts

@@ -1,5 +1,6 @@
 import { Wallet } from "ethers";
 import { describe, it } from "vitest";
+import { ONE_HOUR_MS } from "#/constants";
 import * as ethr from "#/core/did/ethr";
 import { Signer } from "#/core/signer";
 import { Builder } from "#/nuc/builder";
@@ -33,6 +34,7 @@ describe("heterogeneous nuc chain", () => {
       .audience(userDid)
       .subject(userDid)
       .command("/nil/db/data")
+      .expiresIn(ONE_HOUR_MS)
       .sign(rootSigner);
 
     // 2. User (did:ethr) delegates to LegacySvc (did:nil)
@@ -41,12 +43,14 @@ describe("heterogeneous nuc chain", () => {
     )
       .audience(legacySvcDid)
       .command("/nil/db/data/find")
+      .expiresIn(ONE_HOUR_MS / 2)
       .sign(userSigner);
 
     // 3. LegacySvc (did:nil) invokes the command for the FinalSvc
     const invocation = await Builder.invocationFrom(userToLegacySvcDelegation)
       .audience(finalSvcDid)
       .arguments({ id: 123 })
+      .expiresIn(ONE_HOUR_MS / 4)
       .sign(legacySvcSigner);
 
     // Phase 3 - Validation

tests/integration/nilauth.test.ts

@@ -1,5 +1,6 @@
 import { bytesToHex } from "@noble/hashes/utils.js";
 import { beforeAll, describe, expect, it } from "vitest";
+import { ONE_HOUR_MS } from "#/constants";
 import { Did } from "#/core/did/did";
 import { Signer } from "#/core/signer";
 import { Builder } from "#/nuc/builder";
@@ -88,15 +89,22 @@ describe("nilauth client", () => {
     // 2. Delegate root token to a user.
     const userSigner = Signer.generate();
     const userDid = await userSigner.getDid();
+
+    // Calculate parent's remaining lifetime and use a fraction of it
+    const parentExp = rootToken.nuc.payload.exp;
+    const remainingLifetimeMs = (parentExp as number) * 1000 - Date.now();
+
     const userDelegation = await Builder.delegationFrom(rootToken)
       .audience(userDid)
       .subject(userDid)
       .command("/some/specific/capability")
+      .expiresIn(remainingLifetimeMs * 0.8)
       .sign(signer);
 
     // 3. The user invokes their delegation.
     const finalInvocation = await Builder.invocationFrom(userDelegation)
       .audience(await Signer.generate().getDid()) // Some final service
+      .expiresIn(remainingLifetimeMs * 0.5)
       .sign(userSigner); // Signed by the user
 
     // Phase 2: Revoke the intermediate token (userDelegation)
@@ -151,6 +159,7 @@ describe("NilauthClient without a Payer", () => {
       .audience(testDid)
       .subject(testDid)
       .command("/test")
+      .expiresIn(ONE_HOUR_MS)
       .sign(Signer.generate());
 
     // This should succeed as it doesn't require a payer

tests/integration/signer-eip1193-provider.test.ts

@@ -1,5 +1,6 @@
 import type { EIP1193Provider } from "viem";
 import { describe, expect, it, vi } from "vitest";
+import { ONE_HOUR_MS } from "#/constants";
 import { Signer } from "#/core/signer";
 import { Builder } from "#/nuc/builder";
 
@@ -41,6 +42,7 @@ describe("Signer.fromEip1193Provider", () => {
       .audience(audience)
       .subject(did)
       .command("/test")
+      .expiresIn(ONE_HOUR_MS)
       .sign(nucSigner);
 
     // Assert that the signer produced a signature