@sdxc/jwt 2026.10.25 → 2026.11.10

package/README.md

@@ -506,6 +506,26 @@ test("a signed token verifies against the published set", async () => {
 });
 ```
 
+## Command line
+
+```sh
+bunx @sdxc/jwt --help
+```
+
+With [`@sdxc/kit`](https://www.npmjs.com/package/@sdxc/kit) installed, `sdxc pkg jwt …` runs the same command line, using the version your project installs.
+
+```sh
+sdxc-jwt keygen --alg ES256 > key.json                    # a key pair as JSON (--format pem for PEM)
+sdxc-jwt jwks --key-file key.json > jwks.json             # its public key set
+echo '{"sub":"user-123","exp":"15m"}' | sdxc-jwt sign --key-env JWT_KEY
+sdxc-jwt decode "$TOKEN"                                  # header and claims, unverified
+sdxc-jwt verify "$TOKEN" --jwks https://auth.example.com/.well-known/jwks.json --iss https://auth.example.com
+```
+
+Tokens and claims come from an argument, a path or stdin, and keys from `--key-file` or `--key-env`.
+`decode` and `verify` take `--json`. `verify` exits 1 on an invalid token and 2 when its input or
+keys cannot be read.
+
 ## Versioning
 
 Releases are dated rather than semantic. A version is the UTC date it was published, written `YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one release goes out per day.

package/dist/cli-contract.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The `sdxc-jwt` command line as a contract: `decode`, `verify`, `sign`, `keygen` and `jwks`,
+ * with their arguments and flags. Help, usage errors and every handler's typed `ctx.flags`
+ * come from this one declaration.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Every command `sdxc-jwt` takes. */
+export declare const JWT_COMMANDS: import("@sdxc/cli").Group<Omit<{
+    readonly description: "sdxc-jwt — decode, verify and sign JSON Web Tokens, and generate their keys";
+    readonly decode: import("@sdxc/cli").Command<{
+        readonly token: import("@sdxc/cli").Argument<string>;
+    }, {
+        readonly json: import("@sdxc/cli").Flag<boolean>;
+    }>;
+    readonly verify: import("@sdxc/cli").Command<{
+        readonly token: import("@sdxc/cli").Argument<string>;
+    }, {
+        readonly jwks: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+        readonly keyFile: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+        readonly iss: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+        readonly aud: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+        readonly alg: import("@sdxc/cli").ValueFlag<"ES256" | "RS256" | "Ed25519", false, true, false>;
+        readonly json: import("@sdxc/cli").Flag<boolean>;
+    }>;
+    readonly sign: import("@sdxc/cli").Command<{
+        readonly claims: import("@sdxc/cli").Argument<string>;
+    }, {
+        keyFile: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+        keyEnv: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+    }>;
+    readonly keygen: import("@sdxc/cli").Command<Readonly<Record<string, import("@sdxc/cli").Argument<unknown>>>, {
+        readonly alg: import("@sdxc/cli").ValueFlag<"ES256" | "RS256" | "Ed25519", true, false, false>;
+        readonly format: import("@sdxc/cli").ValueFlag<"pair" | "pem", true, false, false>;
+    }>;
+    readonly jwks: import("@sdxc/cli").Command<Readonly<Record<string, import("@sdxc/cli").Argument<unknown>>>, {
+        keyFile: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+        keyEnv: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+    }>;
+}, "description" | "hidden" | "arguments" | "flags" | "tasks">, Record<never, never>, Record<never, never>>;

package/dist/cli-contract.js

@@ -0,0 +1,112 @@
+/**
+ * The `sdxc-jwt` command line as a contract: `decode`, `verify`, `sign`, `keygen` and `jwks`,
+ * with their arguments and flags. Help, usage errors and every handler's typed `ctx.flags`
+ * come from this one declaration.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { argument, command, commands, flag } from "@sdxc/cli";
+import * as s from "remix/data-schema";
+import * as Algorithm from "./algorithm.js";
+/** Every algorithm a key can be generated for or a token verified under. */
+const ALGORITHMS = [Algorithm.ES256, Algorithm.RS256, Algorithm.Ed25519];
+/** A token given on the command line, or `-` (the default) to read it from stdin. */
+const TOKEN = argument(s.string(), {
+    default: "-",
+    valueName: "token",
+    description: "The compact token, or - to read it from stdin",
+});
+/**
+ * Where a key pair from `sdxc-jwt keygen` comes from: a file or a named environment
+ * variable, so the private key stays out of shell history and process listings.
+ */
+const KEY_SOURCE = {
+    keyFile: flag.string("key-file", {
+        valueName: "path",
+        description: "Read the key pair from this file (- for stdin)",
+        heading: "Key",
+    }),
+    keyEnv: flag.string("key-env", {
+        valueName: "name",
+        description: "Read the key pair from this environment variable",
+        heading: "Key",
+    }),
+};
+/** `--json`, for every command that prints a report. */
+const JSON_FLAG = flag.boolean("json", { description: "Print the report as JSON" });
+/** Every command `sdxc-jwt` takes. */
+export const JWT_COMMANDS = commands({
+    description: "sdxc-jwt — decode, verify and sign JSON Web Tokens, and generate their keys",
+    decode: command({
+        description: "Print a token's header and claims without verifying it",
+        arguments: { token: TOKEN },
+        flags: { json: JSON_FLAG },
+        examples: ["decode eyJhbGciOi…", "decode < token.txt --json"],
+    }),
+    verify: command({
+        description: "Check a token's signature, expiry and any expected issuer or audience; exits 1 when it is invalid",
+        arguments: { token: TOKEN },
+        flags: {
+            jwks: flag.string("jwks", {
+                valueName: "url",
+                description: "Verify against the key set served at this URL",
+                heading: "Keys",
+            }),
+            keyFile: flag.string("key-file", {
+                valueName: "path",
+                description: "Verify against a JWKS, a public JWK or a key pair from keygen",
+                heading: "Keys",
+            }),
+            iss: flag.string("iss", { valueName: "issuer", description: "Require this issuer" }),
+            aud: flag.string("aud", { valueName: "audience", description: "Require this audience" }),
+            alg: flag
+                .string("alg", {
+                schema: s.enum_(ALGORITHMS),
+                description: "Accept only this algorithm (repeatable; default: every supported one)",
+            })
+                .multiple(),
+            json: JSON_FLAG,
+        },
+        examples: [
+            "verify $TOKEN --jwks https://auth.example.com/.well-known/jwks.json --iss https://auth.example.com",
+            "verify --key-file jwks.json --aud api < token.txt --json",
+        ],
+    }),
+    sign: command({
+        description: "Sign a JSON object of claims; exp, iat and nbf may be durations such as 1h",
+        arguments: {
+            claims: argument(s.string(), {
+                default: "-",
+                valueName: "claims.json",
+                description: "A JSON file of claims, or - to read them from stdin",
+            }),
+        },
+        flags: KEY_SOURCE,
+        examples: [
+            "sign claims.json --key-file key.json",
+            `echo '{"sub":"user-123","exp":"15m"}' | sign --key-env JWT_KEY`,
+        ],
+    }),
+    keygen: command({
+        description: "Generate a signing key pair, as the JSON sign and verify read or as PEM for other tools",
+        flags: {
+            alg: flag.string("alg", {
+                default: Algorithm.ES256,
+                schema: s.enum_(ALGORITHMS),
+                description: `Algorithm to generate for: ${ALGORITHMS.join(", ")}`,
+            }),
+            format: flag.string("format", {
+                default: "pair",
+                schema: s.enum_(["pair", "pem"]),
+                description: "pair (JSON with id, alg and both PEMs) or pem (private then public key)",
+            }),
+        },
+        examples: ["keygen > key.json", "keygen --alg Ed25519 --format pem"],
+    }),
+    jwks: command({
+        description: "Print the public key set for a key pair, ready to serve as /.well-known/jwks.json",
+        flags: KEY_SOURCE,
+        examples: ["jwks --key-file key.json > jwks.json"],
+    }),
+});

package/dist/cli-decode.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The `sdxc-jwt decode` handler: prints a token's header and claims as the token presents them,
+ * with no key and no checks, for reading a token before deciding how to verify it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+declare const _default: import("@sdxc/cli").CommandAction<import("@sdxc/cli").Command<{
+    readonly token: import("@sdxc/cli").Argument<string>;
+}, {
+    readonly json: import("@sdxc/cli").Flag<boolean>;
+}>, []>;
+export default _default;

package/dist/cli-decode.js

@@ -0,0 +1,21 @@
+/**
+ * The `sdxc-jwt decode` handler: prints a token's header and claims as the token presents them,
+ * with no key and no checks, for reading a token before deciding how to verify it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCommand, success } from "@sdxc/cli";
+import { isFailure } from "@sdxc/result";
+import { JWT_COMMANDS } from "./cli-contract.js";
+import { decodeToken, formatToken, readToken } from "./cli-input.js";
+export default createCommand(JWT_COMMANDS.decode, async (ctx) => {
+    let token = await readToken(ctx.arguments.token, ctx);
+    if (isFailure(token))
+        return token;
+    let decoded = decodeToken(token.data);
+    if (isFailure(decoded))
+        return decoded;
+    ctx.stdout(ctx.flags.json ? `${JSON.stringify(decoded.data)}\n` : formatToken(decoded.data));
+    return success();
+});

package/dist/cli-input.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Input every `sdxc-jwt` command shares: a token from an argument or stdin, a file or stdin
+ * read whole, and a key pair from a file or an environment variable. Input that cannot be read
+ * or parsed answers an exit-2 failure naming its source, so a handler returns it as it is.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Env, ExitError, Stdin } from "@sdxc/cli";
+import type { Result } from "@sdxc/result";
+import type { ProtectedHeaderParameters } from "jose";
+import { JWK } from "./jwk.js";
+import { JWT } from "./jwt.js";
+/** What a command reads its input through. */
+export interface InputContext {
+    cwd: string;
+    env: Env;
+    stdin: Stdin;
+}
+/** A decoded token: its protected header and its claims, both as the token presents them. */
+export interface DecodedToken {
+    header: ProtectedHeaderParameters;
+    payload: JWT.Payload;
+}
+/**
+ * The message of anything thrown, for a diagnostic line.
+ *
+ * @param error - What was caught.
+ */
+export declare function messageOf(error: unknown): string;
+/**
+ * Reads a file whole, or stdin when `source` is `-`. A terminal on stdin is refused, so a
+ * command run with nothing piped exits at once instead of waiting.
+ *
+ * @param source - A path relative to the run's directory, or `-`.
+ * @param ctx - The run's directory and stdin.
+ */
+export declare function readSource(source: string, ctx: InputContext): Promise<Result<string, ExitError>>;
+/**
+ * The token a command was given, trimmed, so a file with a trailing newline reads as the
+ * token it holds.
+ *
+ * @param token - The argument as typed, `-` for stdin.
+ * @param ctx - The run's stdin.
+ */
+export declare function readToken(token: string, ctx: InputContext): Promise<Result<string, ExitError>>;
+/**
+ * Parses JSON read from `source`.
+ *
+ * @param text - The text read.
+ * @param source - Where it came from, for the diagnostic.
+ */
+export declare function parseJSON(text: string, source: string): Result<unknown, ExitError>;
+/**
+ * A token's header and claims, read without verifying the signature.
+ *
+ * @param token - The compact token.
+ */
+export declare function decodeToken(token: string): Result<DecodedToken, ExitError>;
+/**
+ * A decoded token for people: the header and the claims as indented JSON, and when the
+ * token expires.
+ *
+ * @param decoded - The decoded token.
+ */
+export declare function formatToken(decoded: DecodedToken): string;
+/**
+ * Imports a key pair in the shape `sdxc-jwt keygen` writes.
+ *
+ * @param value - The parsed JSON.
+ * @param source - Where it came from, for the diagnostic.
+ */
+export declare function importKeyPair(value: unknown, source: string): Promise<Result<JWK.KeyPair, ExitError>>;
+/**
+ * The key pair named by exactly one of `--key-file` and `--key-env`.
+ *
+ * @param flags - The two flags as given.
+ * @param ctx - The run's directory, environment and stdin.
+ */
+export declare function readKeyPair(flags: {
+    keyFile?: string;
+    keyEnv?: string;
+}, ctx: InputContext): Promise<Result<JWK.KeyPair, ExitError>>;

package/dist/cli-input.js

@@ -0,0 +1,168 @@
+/**
+ * Input every `sdxc-jwt` command shares: a token from an argument or stdin, a file or stdin
+ * read whole, and a key pair from a file or an environment variable. Input that cannot be read
+ * or parsed answers an exit-2 failure naming its source, so a handler returns it as it is.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { EXIT_CODES, exit, success } from "@sdxc/cli";
+import { isFailure } from "@sdxc/result";
+import { decodeProtectedHeader } from "jose";
+import * as s from "remix/data-schema";
+import * as Algorithm from "./algorithm.js";
+import { JWK, LEGACY_EDDSA } from "./jwk.js";
+import { JWT } from "./jwt.js";
+/** The JSON `sdxc-jwt keygen` writes and `JWK.generateKeyPair` answers. */
+const SERIALIZED_KEY_PAIR = s.object({
+    id: s.string(),
+    alg: s.enum_([Algorithm.ES256, Algorithm.RS256, Algorithm.Ed25519, LEGACY_EDDSA]),
+    publicKey: s.string(),
+    privateKey: s.string(),
+    created: s.number(),
+});
+/**
+ * The message of anything thrown, for a diagnostic line.
+ *
+ * @param error - What was caught.
+ */
+export function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Reads a file whole, or stdin when `source` is `-`. A terminal on stdin is refused, so a
+ * command run with nothing piped exits at once instead of waiting.
+ *
+ * @param source - A path relative to the run's directory, or `-`.
+ * @param ctx - The run's directory and stdin.
+ */
+export async function readSource(source, ctx) {
+    if (source === "-") {
+        if (ctx.stdin.isTTY)
+            return exit(EXIT_CODES.usage, "Nothing piped on stdin");
+        return success(await ctx.stdin.text());
+    }
+    try {
+        return success(await readFile(resolve(ctx.cwd, source), "utf8"));
+    }
+    catch (error) {
+        return exit(EXIT_CODES.usage, `Cannot read ${source}: ${messageOf(error)}`);
+    }
+}
+/**
+ * The token a command was given, trimmed, so a file with a trailing newline reads as the
+ * token it holds.
+ *
+ * @param token - The argument as typed, `-` for stdin.
+ * @param ctx - The run's stdin.
+ */
+export async function readToken(token, ctx) {
+    let text = token === "-" ? await readSource(token, ctx) : success(token);
+    if (isFailure(text))
+        return text;
+    let trimmed = text.data.trim();
+    if (trimmed === "")
+        return exit(EXIT_CODES.usage, "No token given");
+    return success(trimmed);
+}
+/**
+ * Parses JSON read from `source`.
+ *
+ * @param text - The text read.
+ * @param source - Where it came from, for the diagnostic.
+ */
+export function parseJSON(text, source) {
+    try {
+        return success(JSON.parse(text));
+    }
+    catch (error) {
+        return exit(EXIT_CODES.usage, `${source} is not valid JSON: ${messageOf(error)}`);
+    }
+}
+/**
+ * A token's header and claims, read without verifying the signature.
+ *
+ * @param token - The compact token.
+ */
+export function decodeToken(token) {
+    try {
+        return success({ header: decodeProtectedHeader(token), payload: JWT.decode(token).payload });
+    }
+    catch (error) {
+        return exit(EXIT_CODES.usage, `Not a JWT: ${messageOf(error)}`);
+    }
+}
+/**
+ * A decoded token for people: the header and the claims as indented JSON, and when the
+ * token expires.
+ *
+ * @param decoded - The decoded token.
+ */
+export function formatToken(decoded) {
+    let lines = [
+        "Header",
+        JSON.stringify(decoded.header, null, 2),
+        "",
+        "Payload",
+        JSON.stringify(decoded.payload, null, 2),
+    ];
+    let token = new JWT(decoded.payload);
+    if (token.expiresAt) {
+        let state = token.expired ? "expired" : "expires";
+        lines.push("", `Token ${state} at ${token.expiresAt.toISOString()}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Imports a key pair in the shape `sdxc-jwt keygen` writes.
+ *
+ * @param value - The parsed JSON.
+ * @param source - Where it came from, for the diagnostic.
+ */
+export async function importKeyPair(value, source) {
+    let parsed = s.parseSafe(SERIALIZED_KEY_PAIR, value);
+    if (!parsed.success) {
+        return exit(EXIT_CODES.usage, `${source} is not a key pair from sdxc-jwt keygen`);
+    }
+    try {
+        return success(await JWK.importKeyPair(parsed.value));
+    }
+    catch (error) {
+        return exit(EXIT_CODES.usage, `${source} holds an unusable key pair: ${messageOf(error)}`);
+    }
+}
+/**
+ * The text of the key pair named by `--key-file` or `--key-env`.
+ *
+ * @param flags - The two flags as given; `keyFile` wins when both are.
+ * @param ctx - The run's directory, environment and stdin.
+ */
+async function readKeyText(flags, ctx) {
+    if (flags.keyFile !== undefined)
+        return readSource(flags.keyFile, ctx);
+    let value = ctx.env[flags.keyEnv ?? ""];
+    if (!value)
+        return exit(EXIT_CODES.usage, `$${flags.keyEnv} is not set`);
+    return success(value);
+}
+/**
+ * The key pair named by exactly one of `--key-file` and `--key-env`.
+ *
+ * @param flags - The two flags as given.
+ * @param ctx - The run's directory, environment and stdin.
+ */
+export async function readKeyPair(flags, ctx) {
+    if ((flags.keyFile === undefined) === (flags.keyEnv === undefined)) {
+        return exit(EXIT_CODES.usage, "Pass exactly one of --key-file <path> or --key-env <name>");
+    }
+    let source = flags.keyFile ?? `$${flags.keyEnv}`;
+    let text = await readKeyText(flags, ctx);
+    if (isFailure(text))
+        return text;
+    let json = parseJSON(text.data, source);
+    if (isFailure(json))
+        return json;
+    return importKeyPair(json.data, source);
+}

package/dist/cli-jwks.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The `sdxc-jwt jwks` handler: prints the public key set for a key pair, carrying only the
+ * public members, so a static issuer can serve it as `/.well-known/jwks.json`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+declare const _default: import("@sdxc/cli").CommandAction<import("@sdxc/cli").Command<Readonly<Record<string, import("@sdxc/cli").Argument<unknown>>>, {
+    keyFile: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+    keyEnv: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+}>, []>;
+export default _default;

package/dist/cli-jwks.js

@@ -0,0 +1,19 @@
+/**
+ * The `sdxc-jwt jwks` handler: prints the public key set for a key pair, carrying only the
+ * public members, so a static issuer can serve it as `/.well-known/jwks.json`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCommand, success } from "@sdxc/cli";
+import { isFailure } from "@sdxc/result";
+import { JWT_COMMANDS } from "./cli-contract.js";
+import { readKeyPair } from "./cli-input.js";
+import { JWK } from "./jwk.js";
+export default createCommand(JWT_COMMANDS.jwks, async (ctx) => {
+    let pair = await readKeyPair(ctx.flags, ctx);
+    if (isFailure(pair))
+        return pair;
+    ctx.stdout(`${JSON.stringify(JWK.toJSON([pair.data]), null, 2)}\n`);
+    return success();
+});

package/dist/cli-keygen.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The `sdxc-jwt keygen` handler: generates a key pair and prints it as the JSON `sign`, `jwks`
+ * and `verify --key-file` read, or as PKCS#8 and SPKI PEM for tools outside this package.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+declare const _default: import("@sdxc/cli").CommandAction<import("@sdxc/cli").Command<Readonly<Record<string, import("@sdxc/cli").Argument<unknown>>>, {
+    readonly alg: import("@sdxc/cli").ValueFlag<"ES256" | "RS256" | "Ed25519", true, false, false>;
+    readonly format: import("@sdxc/cli").ValueFlag<"pair" | "pem", true, false, false>;
+}>, []>;
+export default _default;

package/dist/cli-keygen.js

@@ -0,0 +1,20 @@
+/**
+ * The `sdxc-jwt keygen` handler: generates a key pair and prints it as the JSON `sign`, `jwks`
+ * and `verify --key-file` read, or as PKCS#8 and SPKI PEM for tools outside this package.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCommand, success } from "@sdxc/cli";
+import { JWT_COMMANDS } from "./cli-contract.js";
+import { JWK } from "./jwk.js";
+export default createCommand(JWT_COMMANDS.keygen, async (ctx) => {
+    let pair = await JWK.generateKeyPair(ctx.flags.alg);
+    if (ctx.flags.format === "pem") {
+        ctx.stdout(`${pair.privateKey.trim()}\n${pair.publicKey.trim()}\n`);
+    }
+    else {
+        ctx.stdout(`${JSON.stringify(pair, null, 2)}\n`);
+    }
+    return success();
+});

package/dist/cli-sign.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The `sdxc-jwt sign` handler: signs a JSON object of claims with a key pair from a file or an
+ * environment variable and prints the compact token. `exp`, `iat` and `nbf` may be durations
+ * measured from now, as `new JWT(claims)` reads them.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+declare const _default: import("@sdxc/cli").CommandAction<import("@sdxc/cli").Command<{
+    readonly claims: import("@sdxc/cli").Argument<string>;
+}, {
+    keyFile: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+    keyEnv: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+}>, []>;
+export default _default;

package/dist/cli-sign.js

@@ -0,0 +1,43 @@
+/**
+ * The `sdxc-jwt sign` handler: signs a JSON object of claims with a key pair from a file or an
+ * environment variable and prints the compact token. `exp`, `iat` and `nbf` may be durations
+ * measured from now, as `new JWT(claims)` reads them.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCommand, EXIT_CODES, exit, success, usage } from "@sdxc/cli";
+import { isFailure } from "@sdxc/result";
+import * as s from "remix/data-schema";
+import { JWT_COMMANDS } from "./cli-contract.js";
+import { messageOf, parseJSON, readKeyPair, readSource } from "./cli-input.js";
+import { JWT } from "./jwt.js";
+/** A claim set: a JSON object, any members. */
+const CLAIMS = s.record(s.string(), s.any());
+export default createCommand(JWT_COMMANDS.sign, async (ctx) => {
+    let source = ctx.arguments.claims;
+    if (source === "-" && ctx.flags.keyFile === "-") {
+        return usage("Only one of the claims and the key can come from stdin");
+    }
+    let pair = await readKeyPair(ctx.flags, ctx);
+    if (isFailure(pair))
+        return pair;
+    let text = await readSource(source, ctx);
+    if (isFailure(text))
+        return text;
+    let json = parseJSON(text.data, source === "-" ? "stdin" : source);
+    if (isFailure(json))
+        return json;
+    let claims = s.parseSafe(CLAIMS, json.data);
+    if (!claims.success || Array.isArray(json.data)) {
+        return exit(EXIT_CODES.usage, "The claims must be a JSON object");
+    }
+    try {
+        let token = new JWT(claims.value);
+        ctx.stdout(`${await token.sign(pair.data.alg, [pair.data])}\n`);
+        return success();
+    }
+    catch (error) {
+        return exit(EXIT_CODES.usage, `Cannot sign these claims: ${messageOf(error)}`);
+    }
+});

package/dist/cli-verify.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The `sdxc-jwt verify` handler: checks a token's signature, `exp` and `nbf`, plus any issuer,
+ * audience and algorithms asked for, against a key set from a URL or a file. A token that fails
+ * exits 1; keys that cannot be read exit 2, so a script tells a bad token from a bad setup.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+declare const _default: import("@sdxc/cli").CommandAction<import("@sdxc/cli").Command<{
+    readonly token: import("@sdxc/cli").Argument<string>;
+}, {
+    readonly jwks: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+    readonly keyFile: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+    readonly iss: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+    readonly aud: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+    readonly alg: import("@sdxc/cli").ValueFlag<"ES256" | "RS256" | "Ed25519", false, true, false>;
+    readonly json: import("@sdxc/cli").Flag<boolean>;
+}>, []>;
+export default _default;

package/dist/cli-verify.js

@@ -0,0 +1,117 @@
+/**
+ * The `sdxc-jwt verify` handler: checks a token's signature, `exp` and `nbf`, plus any issuer,
+ * audience and algorithms asked for, against a key set from a URL or a file. A token that fails
+ * exits 1; keys that cannot be read exit 2, so a script tells a bad token from a bad setup.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCommand, EXIT_CODES, exit, failure, success, usage } from "@sdxc/cli";
+import { isFailure } from "@sdxc/result";
+import * as s from "remix/data-schema";
+import { JWT_COMMANDS } from "./cli-contract.js";
+import { decodeToken, formatToken, importKeyPair, messageOf, parseJSON, readSource, readToken, } from "./cli-input.js";
+import { JWK } from "./jwk.js";
+import { JWT } from "./jwt.js";
+/** How long a key set URL has to answer before the run gives up on it. */
+const JWKS_TIMEOUT_MS = 10_000;
+/** One JWK, keeping every member: RFC 7517 requires only `kty`. */
+const KEY = s.object({ kty: s.string() }, { unknownKeys: "passthrough" });
+/** A JWKS document. */
+const KEY_SET = s.object({ keys: s.array(KEY) });
+/**
+ * Fetches the key set served at `url`.
+ *
+ * @param url - What `--jwks` was given.
+ * @param signal - Aborted when the run is cancelled.
+ */
+async function fetchKeys(url, signal) {
+    let parsed = URL.parse(url);
+    if (!parsed || (parsed.protocol !== "https:" && parsed.protocol !== "http:")) {
+        return exit(EXIT_CODES.usage, `--jwks expects an http(s) URL; got ${url}`);
+    }
+    try {
+        let response = await fetch(parsed, {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.any([signal, AbortSignal.timeout(JWKS_TIMEOUT_MS)]),
+        });
+        if (!response.ok)
+            return exit(EXIT_CODES.usage, `${url} answered ${response.status}`);
+        return parseJSON(await response.text(), url);
+    }
+    catch (error) {
+        return exit(EXIT_CODES.usage, `Cannot fetch ${url}: ${messageOf(error)}`);
+    }
+}
+/**
+ * The key set in `value`, which may be a JWKS document, one public JWK, or a key pair from
+ * `sdxc-jwt keygen` (its public half).
+ *
+ * @param value - The parsed JSON.
+ * @param source - Where it came from, for the diagnostic.
+ */
+async function toKeySet(value, source) {
+    let set = s.parseSafe(KEY_SET, value);
+    if (set.success)
+        return success(set.value);
+    let key = s.parseSafe(KEY, value);
+    if (key.success)
+        return success({ keys: [key.value] });
+    let pair = await importKeyPair(value, source);
+    if (isFailure(pair)) {
+        return exit(EXIT_CODES.usage, `${source} is not a JWKS, a JWK or a key pair from keygen`);
+    }
+    return success(JWK.toJSON([pair.data]));
+}
+/**
+ * The key set named by exactly one of `--jwks` and `--key-file`.
+ *
+ * @param flags - The two flags as given.
+ * @param ctx - The run's directory, stdin and abort signal.
+ */
+async function readKeys(flags, ctx) {
+    let source = flags.jwks ?? flags.keyFile ?? "";
+    let text = flags.jwks
+        ? await fetchKeys(flags.jwks, ctx.signal)
+        : await readSource(source, ctx).then((read) => isFailure(read) ? read : parseJSON(read.data, source));
+    if (isFailure(text))
+        return text;
+    return toKeySet(text.data, source);
+}
+export default createCommand(JWT_COMMANDS.verify, async (ctx) => {
+    let { jwks, keyFile, iss, aud, alg, json } = ctx.flags;
+    if ((jwks === undefined) === (keyFile === undefined)) {
+        return usage("Pass exactly one of --jwks <url> or --key-file <path>");
+    }
+    if (keyFile === "-" && ctx.arguments.token === "-") {
+        return usage("Only one of the token and the key set can come from stdin");
+    }
+    let token = await readToken(ctx.arguments.token, ctx);
+    if (isFailure(token))
+        return token;
+    let keys = await readKeys({ jwks, keyFile }, ctx);
+    if (isFailure(keys))
+        return keys;
+    try {
+        await JWT.verify(token.data, await JWK.importLocal(keys.data), {
+            issuer: iss,
+            audience: aud,
+            algorithms: alg.length > 0 ? alg : undefined,
+        });
+    }
+    catch (error) {
+        let reason = messageOf(error);
+        if (!json)
+            return failure(new Error(`Invalid token: ${reason}`));
+        ctx.stdout(`${JSON.stringify({ valid: false, error: reason })}\n`);
+        return exit(EXIT_CODES.failure);
+    }
+    let decoded = decodeToken(token.data);
+    if (isFailure(decoded))
+        return decoded;
+    if (json)
+        ctx.stdout(`${JSON.stringify({ valid: true, ...decoded.data })}\n`);
+    else
+        ctx.stdout(`Valid token\n\n${formatToken(decoded.data)}`);
+    return success();
+});

package/dist/cli.d.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * The `sdxc-jwt` command-line program: the contract in `cli-contract.ts` with each command mapped
+ * onto its handler, which loads only when that command runs. Exit codes: 0 done, 1 an invalid
+ * token, 2 usage or unreadable input.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** The `sdxc-jwt` program, run by the bin entry below and by tests through `invoke()`. */
+export declare const cli: import("@sdxc/cli").CLI<import("@sdxc/cli").Group<Omit<{
+    readonly description: "sdxc-jwt — decode, verify and sign JSON Web Tokens, and generate their keys";
+    readonly decode: import("@sdxc/cli").Command<{
+        readonly token: import("@sdxc/cli").Argument<string>;
+    }, {
+        readonly json: import("@sdxc/cli").Flag<boolean>;
+    }>;
+    readonly verify: import("@sdxc/cli").Command<{
+        readonly token: import("@sdxc/cli").Argument<string>;
+    }, {
+        readonly jwks: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+        readonly keyFile: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+        readonly iss: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+        readonly aud: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+        readonly alg: import("@sdxc/cli").ValueFlag<"ES256" | "RS256" | "Ed25519", false, true, false>;
+        readonly json: import("@sdxc/cli").Flag<boolean>;
+    }>;
+    readonly sign: import("@sdxc/cli").Command<{
+        readonly claims: import("@sdxc/cli").Argument<string>;
+    }, {
+        keyFile: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+        keyEnv: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+    }>;
+    readonly keygen: import("@sdxc/cli").Command<Readonly<Record<string, import("@sdxc/cli").Argument<unknown>>>, {
+        readonly alg: import("@sdxc/cli").ValueFlag<"ES256" | "RS256" | "Ed25519", true, false, false>;
+        readonly format: import("@sdxc/cli").ValueFlag<"pair" | "pem", true, false, false>;
+    }>;
+    readonly jwks: import("@sdxc/cli").Command<Readonly<Record<string, import("@sdxc/cli").Argument<unknown>>>, {
+        keyFile: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+        keyEnv: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+    }>;
+}, "description" | "hidden" | "arguments" | "flags" | "tasks">, Record<never, never>, Record<never, never>>, []>;

package/dist/cli.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * The `sdxc-jwt` command-line program: the contract in `cli-contract.ts` with each command mapped
+ * onto its handler, which loads only when that command runs. Exit codes: 0 done, 1 an invalid
+ * token, 2 usage or unreadable input.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCLI, lazy } from "@sdxc/cli";
+import { JWT_COMMANDS } from "./cli-contract.js";
+/** The `sdxc-jwt` program, run by the bin entry below and by tests through `invoke()`. */
+export const cli = createCLI({ name: "sdxc-jwt", commands: JWT_COMMANDS });
+cli.map(JWT_COMMANDS.decode, lazy(() => import("./cli-decode.js")));
+cli.map(JWT_COMMANDS.verify, lazy(() => import("./cli-verify.js")));
+cli.map(JWT_COMMANDS.sign, lazy(() => import("./cli-sign.js")));
+cli.map(JWT_COMMANDS.keygen, lazy(() => import("./cli-keygen.js")));
+cli.map(JWT_COMMANDS.jwks, lazy(() => import("./cli-jwks.js")));
+if (import.meta.main) {
+    process.exit(await cli.run(process.argv.slice(2)));
+}

package/package.json

@@ -1,8 +1,11 @@
 {
 	"name": "@sdxc/jwt",
-	"version": "2026.10.25",
+	"version": "2026.11.10",
 	"description": "JWT payload classes and the keys that sign them",
 	"license": "MIT",
+	"bin": {
+		"sdxc-jwt": "dist/cli.js"
+	},
 	"type": "module",
 	"exports": {
 		".": "./dist/index.js",
@@ -10,12 +13,14 @@
 		"./r2": "./dist/r2-key-storage.js"
 	},
 	"dependencies": {
+		"@sdxc/cli": "2026.11.10",
 		"@sdxc/duration": "2026.10.13",
 		"@sdxc/result": "2026.10.13",
-		"@sdxc/uuid": "2026.10.13",
-		"jose": "^6.2.13"
+		"@sdxc/uuid": "2026.11.10",
+		"jose": "^6.2.13",
+		"remix": "3.2.0"
 	},
-	"gitHead": "1440b969c0a3e3808dfcee3f17d2ef43915f32a8",
+	"gitHead": "6191b60a13885b1d826884d574c4a393f9b8eeee",
 	"publishConfig": {
 		"access": "public"
 	},