Merge pull request #74 from NillionNetwork/fix/check-epochs-in-seconds

fix: add epoch timestamp parsing for token validity checks

Author: pablojhl

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nillion/nuc",
-  "version": "0.1.0-rc.8",
+  "version": "0.1.0-rc.9",
   "license": "MIT",
   "repository": "https://github.com/NillionNetwork/nuc-ts",
   "engines": {

src/builder.ts

@@ -11,7 +11,12 @@ import {
   NucToken,
   NucTokenDataSchema,
 } from "#/token";
-import { base64UrlEncode, type Hex, randomBytes } from "#/utils";
+import {
+  base64UrlEncode,
+  type Hex,
+  parseEpochSeconds,
+  randomBytes,
+} from "#/utils";
 
 const DEFAULT_NONCE_LENGTH = 16;
 
@@ -102,9 +107,11 @@ export class NucTokenBuilder {
   /**
    * Set the token's `not before` instant.
    *
-   * @param notBeforeInSeconds The Unix timestamp (in seconds) at which the token becomes valid.
+   * @param epoch The Unix timestamp (in seconds) at which the token becomes valid.
+   * @throws Error if the value is not a valid epoch timestamp.
    */
-  notBefore(notBeforeInSeconds: number): NucTokenBuilder {
+  notBefore(epoch: number): NucTokenBuilder {
+    const notBeforeInSeconds = parseEpochSeconds(epoch);
     this._notBefore = Temporal.Instant.fromEpochMilliseconds(
       notBeforeInSeconds * 1000,
     );
@@ -114,9 +121,11 @@ export class NucTokenBuilder {
   /**
    * Set the token's `expires at` instant.
    *
-   * @param expiresAtInSeconds The Unix timestamp (in seconds) at which the token expires.
+   * @param epoch The Unix timestamp (in seconds) at which the token expires.
+   * @throws Error if the value is not a valid epoch timestamp.
    */
-  expiresAt(expiresAtInSeconds: number): NucTokenBuilder {
+  expiresAt(epoch: number): NucTokenBuilder {
+    const expiresAtInSeconds = parseEpochSeconds(epoch);
     this._expiresAt = Temporal.Instant.fromEpochMilliseconds(
       expiresAtInSeconds * 1000,
     );

src/nilauth/types.ts

@@ -1,6 +1,7 @@
 import { Temporal } from "temporal-polyfill";
 import z from "zod";
 import { NucTokenEnvelopeSchema } from "#/envelope";
+import { EpochSeconds } from "#/utils";
 
 const PUBLIC_KEY_LENGTH = 66;
 
@@ -59,8 +60,8 @@ export type SubscriptionCostResponse = z.output<
 
 export const SubscriptionDetailsSchema = z
   .object({
-    expires_at: z.number(),
-    renewable_at: z.number(),
+    expires_at: EpochSeconds,
+    renewable_at: EpochSeconds,
   })
   .transform(({ expires_at, renewable_at }) => ({
     expiresAt: Temporal.Instant.fromEpochMilliseconds(expires_at * 1000),
@@ -84,7 +85,7 @@ export type CreateTokenResponse = z.infer<typeof CreateTokenResponseSchema>;
 export const RevokedTokenSchema = z
   .object({
     token_hash: z.string(),
-    revoked_at: z.number(),
+    revoked_at: EpochSeconds,
   })
   .transform(({ token_hash, revoked_at }) => ({
     tokenHash: token_hash,

src/token.ts

@@ -3,7 +3,7 @@ import { dequal } from "dequal";
 import { Temporal } from "temporal-polyfill";
 import { z } from "zod";
 import { type Policy, PolicySchema } from "#/policy";
-import { type Hex, HexSchema } from "#/utils";
+import { EpochSeconds, type Hex, HexSchema } from "#/utils";
 
 const DID_EXPRESSION = /^did:nil:([a-zA-Z0-9]{66})$/;
 
@@ -123,8 +123,8 @@ export const NucTokenSchema = z
     iss: DidSchema,
     aud: DidSchema,
     sub: DidSchema,
-    nbf: z.number().optional(),
-    exp: z.number().optional(),
+    nbf: EpochSeconds.optional(),
+    exp: EpochSeconds.optional(),
     cmd: CommandSchema,
     args: InvocationBodySchema.optional(),
     pol: DelegationBodySchema.optional(),

src/utils.ts

@@ -13,6 +13,31 @@ export const HexSchema = z.string().regex(/^[a-fA-F0-9]+$/, "invalid hex");
 /** Type for a validated hexadecimal string. */
 export type Hex = z.infer<typeof HexSchema>;
 
+/**
+ * Epoch timestamp in seconds.
+ **/
+export const EpochSeconds = z.number().int().max(1e12);
+/**
+ * Parses a value as an epoch timestamp in seconds.
+ *
+ * Validates that the value is an integer and does not exceed 1 trillion.
+ * Throws a ZodError if validation fails.
+ *
+ * @param value - The value to parse as epoch seconds.
+ * @returns The parsed epoch seconds as a number.
+ * @throws Error if the value is not a valid epoch timestamp.
+ * @example
+ * parseEpochSeconds(1633036800) // Returns 1633036800
+ * parseEpochSeconds("invalid") // Throws Error
+ */
+export const parseEpochSeconds = (value: unknown): number => {
+  try {
+    return EpochSeconds.parse(value);
+  } catch (_e) {
+    throw new Error(`Invalid epoch: ${value}`);
+  }
+};
+
 /**
  * Converts a UTF-8 string to hexadecimal.
  *